IAS/RSX-11 


I/O Operations Reference Manual 
Order No. AA-M176A-TC 


RSX-11M Version 4.0 
RSX-11M-PLUS Version 2.0 
IAS Version 3.1 


digital equipment corporation - maynard, massachusetts 


First Printing, December 1975 
Revised, December 1976 
Revised, December 1977 

Revised, June 1979 
Revised, November 1981 


The information in this document is subject to change without notice 
and should not be construed aS a commitment by Digital Equipment 
Corporation. Digital Equipment Corporation assumes no responsibility 
for any errors that may appear in this document. 


The software described in this document is furnished under a license 
and may be used or copied only in accordance with the terms of such 
license. 


No responsibility is assumed for the use or reliability of software on 
equipment that is not supplied by Digital Equipment Corporation or its 


— oo me 


ae ee S| 
G@LLILLLGALTU CUNMpPAlLede 


Copyright © 1975, 1976, 1977, 1979, 1981 
by Digital Equipment Corporation 
All Rights Reserved. 


Printed in U.S.A. 


The postpaid READER'S COMMENTS form on the last page of this document 
requests the user's critical evaluation to assist in preparing future 
documentation. 


The following are trademarks of Digital Equipment Corporation: 


DEC EduSystem RSX 
DECnet IAS UNIBUS 
DECsystem-10 MASSBUS VAX 
DECSYSTEM-20 PDP VMS 
DECUS PDT 


pecwriter STS POROceD 


ZK2058 


CONTENTS 


Page 
PREFACE xi 
SUMMARY OF TECHNICAL CHANGES xiii 
CHAPTER 1] FILE CONTROL SERVICES 
be A PILE ACCESS METHODS: 6.6: 6. «dee ee ee a wo LS? 
Dg2 FILE STORAGE REGION (FSR) tS le Wee ie Re ena ee sare en BS a ee 
Les DATA FORMATS FOR FILE-STRUCTURED DEVICES .... . 1-3 
ere Data Formats for ANSI Magtape ......... 1-4 
1.4 BLOCK. 1/70: -OPERATLONG© gob) 6 a et eee! ee ee ee el wh See ES 
eg RECORD I/O OPERATIONS ..... © © © «© «© «© « © « 1-5 
1.6 DATA-TRANSFER MODES .... .« © «© «© «© «© «© © «© « « 1-6 
Ls6./1 MOvVe “MOGG: ° 6% 40 ee as le Ee we 9 OR we Se we ER 
L672 Locate Mode ... a oO wes Se ee Say, Hae ow Say Se a Sa Oe, AS 
bee MULTIPLE BUFFERING FOR RECORD .1/0° 4% <6 6) ce cece Sa 16 
1.8 SHARED ACCESS: “TO PILES...) ais 36 ew Se Je td a a TSB 
1.9 FILE DESCRIPTOR BLOCK (FDB) oy Hes 20. <6 e 1-10 
1.10 DATASET DESCRIPTOR AND DEFAULT FILENAME. BLOCK 7 1-10 
B ierias 5 0 KEY TERMS USED THROUGHOUT THIS MANUAL ..... 1-10 
1.12 Diolem CHARACTERISTICS. g <e! “s 4: ee es we! we te eS 1-12 
CHAPTER 2 PREPARING FOR I/0 
2.1 -MCALL DIRECTIVE - LISTING NAMES OF REQUIRED MACRO 
DEFINITIONS ... : we We es See ee CE ROSS SE ae ZZ 
2e2 FILE DESCRIPTOR BLOCK (FDB) Bee Se Se te hs ce ZS 
Deeak Assembly-Time FDB Initialization Macros .. . 2-3 
Z2e2edst FDBDF$ - Allocate File Descriptor Block (PDB) 2-5 
2c2ele2 FDATSA - Initialize File Attribute Section 
of PDB 6 soe Ge ee ee SS Sar le te ow ee ws Se oe ZS 


Die 2e les FDRCSA —- Initialize Record Access Section of 
FDB e e e s e s s s e e e ee e e e e e e . e e 2-8 


2526.64 FDBKSA - Initialize Block Access Section of 

PDB. vet was Be Ghee Ene Be wee a A es eae ee ele SLD 
Ae 25 FDOPSA - Initialize File-Open Section of FDB 2-13 
2g 26 66 FDBFSA - Initialize Block Buffer Section of 


FDB e . e e e ° . e e e e ° e ° ° e ° ° e e 2-17 


2eo52 Run-Time FDB Initialization Macros ...... 2-21 
2eee Lad Run-Time FDB Macro-Call Exceptions ..... 2-21 
Ze2etee Specifying the FDB Address in Run-Time 
MACTO CALES 6 wre: we oe ve eS . ° ° - 2-24 
203 GLOBAL VERSUS LOCAL DEFINITIONS FOR FDB OFFSETS 2-25 
Ze oe Specifying Global Symbols in the Source Coding 2-25 
223.2 Defining FDB Offsets and Bit Values Locally . 2-26 
2.4 CREATING FILE SPECIFICATIONS WITHIN THE USER 
PROGRAM «.6> ete. ae ee a se a a, ee ae ee ee EG 
2.4.1 Dataset: DESCTIPEOr .c--ce ie SS we. ee ee we He ZB 


CHAPTER 


. 
NO 


oe ee @ 
° 
Nr 


NNNMNNNNNNN NY 
emU. 
Ore 


DDWDAAYIANIAYNAANHW 


o oe 
WN 


e e e 


3.18 
3.18.1 


Default Filename Block - NMBLKS$ Macro Call. . 
Dynamic Processing of File Specifications .. 
OPTIMIZING FILE ACCESS . .« « « «© «© «© «© «© © © @ 
Initializing the Filename Block As a Function 
of OPENSx .... le pee ee ee ee “ecg wer eS 
Manually Initializing the Filename Block... 
INITIALIZING THE FILE STORAGE REGION ...... 
FSRSZS - Initialize FSR at Assembly Time... 
FINITS - Initialize FSR at Run Time ... 
INCREASING THE SIZE OF THE FILE STORAGE REGION . 
FSR-Extension Procedures for MACRO-11 Programs 
FSR-Extension Procedures for FORTRAN Programs 
COORDINATING I/O OPERATIONS .. 
Event FlagS . . . «.« « « « « « 


I/O Status Block ..... . 
AST Service Routine .... 


es e e 
e e e es e 
e e e 


FILE-PROCESSING MACRO CALLS 


OPENSX - GENERALIZED OPEN MACRO CALL ...... 
Format of Generalized OPENS$x Macro Call ... 
FDB Requirements for Generalized OPENSx Macro 
Calls * Sis de a Sve ° ee ee BO SR 

OPNSSX - OPEN FILE FOR SHARED ACCESS o © © © «© © 

OPNTSW - CREATE AND OPEN TEMPORARY FILE . 

OPNTSD - CREATE AND OPEN TEMPORARY FILE AND "MARK 

FOR DELETION... e Bh oe) eo Ses ee Se: Se OS ee a 

OFIDSX - OPEN FILE BY FILE BD, i aes tale cate alee 

OFNBSX OPEN FILE BY FILENAME BLOCK ...... - 
Dataset Descriptor and/or Default Filename 
BLOCK # &'&% : ee Gan ae i Ses ek tee ae 
Default filename Block Only ce Sue 

OPENS - GENERALIZED OPEN FOR SPECIFYING "PILE 

PCCESS > id, Scueieeh hee cet ee a fa! ee ae ee ae SES ee Sa 

CLOSES - CLOSE SPECIFIED FILE ee Ser Wel AR Se) oe Gi 
Format of CLOSES Macro Call ......«-+-e-. 

GETS - READ LOGICAL RECORD ......« « « « « « 
Format of GETS Macro Call ..... «2 2 « « 
FDB Mechanics Relevant to GETS Operations . 

GETS Operations in Move Mode oe 8 GE we 
GETS Operations in Locate Mode we fae lore. a> 

GETSR - READ LOGICAL RECORD IN RANDOM MODE . . 

GETSS - READ LOGICAL RECORD IN SEQUENTIAL MODE 

PUTS - WRITE LOGICAL RECORD .......e. 
Format of PUTS Macro Call .....-+-e-e-. 
FDB Mechanics Relevant to PUTS Operations . 

PUTS Operations in Move Mode ....... 
PUTS Operations in Locate Mode... . ; 

PUTSR - WRITE LOGICAL RECORD IN RANDOM MODE . 

PUTSS - WRITE LOGICAL RECORD IN SEQUENTIAL MODE 

READS —- READ VIRTUAL BLOCK . ..... +. + «© « » 
Format of READS Macro Call... . ° 
FDB Requirements for READS Macro Call 

WRITES - WRITE VIRTUAL BLOCK ...... 
Format of WRITES Macro Call ..... 
FDB Requirements for WRITES Macro Call 

WAITS = WAIT FOR BLOCK I/O COMPLETION 
Format of WAITS Macro Call ..... 

DELETS ~- DELETE SPECIFIED FILE... . 
Format of DELETS Macro Call .... 


e e ° e e e e e 
e e e e e e e e e 
e e e e e e e ° 


iv 


CHAPTER 


CONTENTS 


FILE CONTROL ROUTINES 


CALLING FILE CONTROL ROUTINES .....-.-e«-«- 
DEFAULT DIRECTORY-STRING ROUTINES .....e.. 
»-RDFDR - Read $SFSR2 Default Directory String 
Descriptor ... . oe. ee See ae “ae ce 
~WDFDR - Write New S$FSR2 Default 
Directory-String Descriptor .......e.-. 
DEFAULT UIC ROUTINES . . « « © © © © © e e © © «@ 
»~RDFUI - Read Default UIC .......... 
-WDFUI - Write Default UIC .... ee. wel ee & 
DEFAULT FILE-PROTECTION WORD ROUTINE Ss. ° ° 
-RDFFP - Read SSFSR2 Default File Protection 
Word . « 6 © « « « « « P . ca cles “ar. Se) Sa oS 
-WDFFP - Write New $$FSR2 Default 
File-Protection Word . . « « « « « «© « «© « @ « 
FILE OWNER WORD ROUTINES ..... o © «© © 
-RFOWN - Read SSFSR2 File Owner Word oe err 4 
-WFOWN - Write New SSFSR2 File Owner Word .. 
ASCII/BINARY UIC CONVERSION ROUTINES ...... 
-ASCPP - Convert ASCII Directory String to 
Equivalent Binary UIC .... 3 ° 
-PPASC - Convert UIC to ASCII Directory String 
FILENAME BLOCK ROUTINES ... . C.sBe, el ue fer we 
-PARSE - Fill in All Filename Information o 8 
Device and Unit Information ......ee. 
Directory Identification Information... . 
File Name, File Type or Extension, and File 
Version Information .. . 2... « « «© «© ee 
Other Filename Block Information ...... 
-PRSDV - Fill in Device and Unit Information 
ONLY ie: era ee a2 ods, Sele BS a te en ae na BB Be ta 8 
»~PRSDI - Fill in 1 Directory Identification 
Inftormatvon OALY «. 6.6. ear Se. we Boe: CW a ee ee 
-PRSFN - Fill in File name, File Type or 
Extension, and File Version Only ....... 
-ASLUN - Assign Logical Unit Number ..... 
DIRECTORY ENTRY ROUTINES . . 2. « « © © © «© © «© «@ 
-FIND - Locate Directory Entry ......e. 
~ENTER - Insert Directory Entry .....e. 
~REMOV - Delete Directory Entry ....... 
FILENAME BLOCK ROUTINES .... .« « « «© « «© © « 
-GTDIR - Insert Directory Information in 
Filename Block ..... ee ee a ee ee 
-GTDID - Insert Default Directory Information 
in. Filename BLOCK. «- «6, 6-6 e- WW oer Car Sis 
FILE POINTER ROUTINES ... © ° e, jas 8 
-POINT - Position File to Specified Byte &. he 
-POSRC - Position File to Specified Record. . 
-MARK - Save Positional Context of File ... 
-POSIT - Return Positional Information for 
Specified Record . ....e. Si sai Wah a> 8 ah, Me 
QUEUE I/O FUNCTION ROUTINE (. XQIO) oe ee 
RENAME FILE ROUTINE (.RENAM) . . «© « « «© «© « « «@ 
FILE EXTENSION ROUTINE (.EXTND) oe © we ew ew ew 
FILE TRUNCATION ROUTINE (.TRNCL) . . . «© « «© « « 
FILE DELETION ROUTINES .... . o © © © ew ew 
-MRKDL - Mark Temporary File for Deletion .. 
-DLFNB - Delete File by Filename Block .... 
DEVICE CONTROL ROUTINE (.CTRL) . .© « « «© « « © « 


Page 


0 
1 ot 
NNN UU 


mh Ph Ph 
I Ist 


t 
Oo MO~AI~I~ 


& 
t 
e 


CHAPTER 


CHAPTER 


CHAPTER 


5 


e e e e e e e e e 
e e e e e e e 


NONNNNNNNNNNNDNF HERE FH 


AMMMNANMOaINnNNannnninwg v1 


NAIA NUP WN 


~] 


ee ee ee ee ee ee 
eRe epee oe eee 
re es Che ar wr 
We 


FILE STRUCTURES 


DISK AND DECTAPE FILE STRUCTURE (FILES-11) . 
User File Structure: 6.6 (6 6: wee es i eS 
Directory: Files. vse Sees hee ie we. Se es i ee ew 
ENGex: Fi Le: ce Si ae. Ge se eek  e S 
File Header Block .... a. fae? de - 

MAGNETIC TAPE FILE PROCESSING eo 2 © «6 
Access to Magnetic Tape Volumes .. 
Rewinding Volume Sets ....... 
Positioning to the Next File Position 
Single-File Operations . .....e.e. 
Multiple-File Operations ....... 
USING: «CERE. vc te eg cer Wee er et Wee wt Ke 
Examples of Magnetic Tape Processing... 

Examples of OPENSW to Create a New File 
Examples of OPENSR to Read a File ... 
Examples of CLOSES ..... . 
Combined Examples of OPENS and CLOSES for 
Magnetic “Tape 2c: @ “<9 @ wl ee oe ote 


e 
e 
e 
e 


COMMAND LINE PROCESSING 


_ GET COMMAND LINE (GCML) eo 8 © © © we ew ew 


GCMLBS - Alilocate and Initialize GCML Contr 
Block ... “ 
GCMLDS - Define GCML Control Block Offsets 
Bits VAIS ge Se Ga ee en ek BREE a EOS 
GCML Run-Time Macro CallS ......e«.- 
GCMLS$ - Get Command Line ...... 
RCMLS - Reset Indirect Command File Sean 
CCML$ - Close Current Command File... 
GCML Usage Considerations ......e. 
COMMAND STRING INTERPRETER (CSI)... 


CSIS -— Define CSI Control Block Offsets ‘ena Bit 


Tr 


Values ° e e e e 
CSI Control "Block “Of Fset and Bit Value 
DELINIEIONS:- cite. we a6 iS Goode ep et ar a 
CSI Run-Time Macro Calls .... . 
CSI$1 - Command Syntax Analyzer. ‘ 


CSIS2 —- Command Semantic Parser é 
CSI Switch Definition Macro Calls 


CSISSW - Create Switch Descriptor Table Entry 
CSISSV - Create Switch Value Descriptor Table 


Entry .. ee ° . os ° 
CSISND - Define End of Descriptor Table 
THE TABLE-DRIVEN PARSER (TPARS) 


CODING TPARS SOURCE PROGRAMS . . ° 
TPARS Macros: ISTATS, STATES, and “TRANS ‘. 


ol 


and 


e e e e e e e e e 


Initializing the State Table: the ISTATS Macro 
Defining a Syntax Element: the STATES Macro 


Defining a Transition: the S$TRAN Macro . 

Types of Command Line Syntax Elements .. 

Action Routines and Built-in Variables .. 
TPARS Built-in Variables ........ 
Calling Action Routines ......2... 
Using Action Routines to Reject a 
Transition... ° 6 © © © © ew ew ltl lt 


Optional Debug Routine for RSX-1l Users 


vi 


Page 


btiettttttt ttt @ tt 
DANN AHATCUMUNUNS HPWH NE bF 


Moron Ow oro On U1 WI U1 U1 
t 


s~ 4s J S S) ~~) 
| 
DUT S&WWN DF 


~] ~l 
I 
OV ON 


CHAPTER 


APPENDIX 


APPENDIX 


APPENDIX 


APPENDIX 


APPENDIX 


~J ~J ~! 
«ee 
NN He 
e e 
— ns 


eee ee ee 
ee eee 
Nr Hm WN 


Sn ee i ee ne i i 
e 
HDHDAV & PS WDHY DN DN 

e 
Ne 


APPENDIX G 


e 
ee 
e 


e 
OPW WNH F&F 


ARAAAAAA 


e 
~ 


e 
e 


HOW TO GENERATE A PARSER PROGRAM USING 
PROGRAMMING EXAMPLES . 2. 2. «© «© «© © © © © © © @ « 


SUMMARY OF I/0O-RELATED 


HEADER AREA ....- 
IDENTIFICATION AREA . 
MAP AREA : 


SUPPORT OF ANSI MAGNETIC 


CONTENTS 


TPARS~SUDEXPFESSIONS ¢ -%- ee we Rw BP SS a 


GENERAL CODING CONSIDERATIONS .... . nd 


Suggested Arrangement of Syntax Types ina 
Table. 6 6.68 fer cw. 6; Me ws a ew 8 te Se 
Ignoring Blanks and Tabs in a Command Line. . 
Entering Special Characters .. «+2 « * * #.* 
Recognition of Keywords . ge nile ape Tee as we 


PSECTS GENERATED BY¥ TPARS MACROS Se ee re ey far Sai 
INVOKING TPARS . e e e s e e e e e e e e e e e eo 


Register Usage and Calling Conventions .... 
Using the Options Word ..... 


TPARS .. 


Parsing a UFD Command Line . ......e--. 
How to Use Subexpressions and Reject 

TYANSIULONS: - 6." 16. fer fer A Be ei eee 
Using Subexpressions to Parse Complex Grammars 


SPOOLING 


PRINTS MACRO CALL. 5 2d 4 ww ew ae we ee 8 
e PR INT SUBROUTINE e e se e e e e e e e e s es eo e 
ERROR HANDLING s e e e es es e s e se es es s e e e e 


FILE DESCRIPTOR BLOCK 


FILENAME BLOCK 


SYSTEM DIRECTIVES 


SAMPLE PROGRAMS 


INDEX FILE FORMAT 


BOOTSTRAP BLOCK .... « « © « © © © © «© «© @ « 
HOME BLOCK . . . -« «© © © © © © © © © © © © © © « 
INDEX FILE BIT MAP . 2... «© « © « © © © © «© © © «@ 
PREDEFINED FILE HEADER 


BLOCKS e e e e ° e e e e 


FILE HEADER BLOCK FORMAT 


o e e 
» e 
e 

o e e 

o e e 

o @ @ 
e 
e 

0 e e 
e 

o @ @ 
e 


esate = s. = . . = 


TAPE STANDARD 


VOLUME AND FILE LABELS ....-. « « © © © © « « 


Volume Label Format ...... « «© « « © e« « 

Contents of Owner Identification Field... 
User Volume LabelS . ..... « « «© «© © «© «© «@ 
File Header Labels ..... ° cs ee 

File Identifier Processing by Files- 11 a ey 
End-of-Volume LabelS . . .« « « « «© © © « e « « 
File Trailer LabelS .......e 2 « « «© « « 


vii 


~~] ~J 
t | 
co ~] 


J ~~] ~J 
| 


~ 

! 

ae 
Ow wo Wc 


7-11 


5 aba Vi ae ale es 
~sJI—I OVW WN FE 


Page 
G.1.6 User File Labels: a <6: %. soe wi a fe 4S OS oe ao ey oe G8 
G.2 FILE STRUCTURES .... Se ue, “eed at “we be ine Hes a GSO 
G.2.1 Single File Single Volume oo? Cab oes we Ww 1 Ge 1 GSS 
G.2.2 Single File Multivolume ........ +... G-8 
G.2.3 Multifile Single Volume ......-. +... G-8 
G.2.4 Multifile Multivolume . . . . « © « « «© s «e « « G-8 
G.3 END-OF-TAPE HANDLING .... be Be le ae ee ale ee a GHD 
G.4 ANSI MAGNETIC TAPE FILE HEADER BLOCK (FCS 
COMPATIBLE) ot by, Bi Gee ° ele «gtr See Se! See, sae eG" 
G.5 THE MAGNETIC TAPE CONTROL TASK a0 ete @ (Bw ae we ce GTO 
G.6 UNLABELED TAPE. «6 0 « @ «2 6» #8 « «6 «© « «© « Gel4 
G.6.1 Tape. Positioning «sc «cw sore es. wo wa we we es &- OGRLTS 
G.6.2 Specifying File Attributes . ......e..e. G-15 
G.6.3 Translation ... a ae oe ee iH. ei ce to GETS 
G.6.4 Example of EBCDIC Translation Tables oe ee tee “Gado 
G.7 EXAMPLE USING AN INDIRECT COMMAND FILE TO READ A 
TAPE se) Ses feces ar cei es ete al a Be we, ese GEL 
APPENDIX H STATISTICS BLOCK 
APPENDIX I ERROR CODES 
APPENDIX J FIELD SIZE SYMBOLS 


APPENDIX K RSX-11M/M-PLUS FCS LIBRARY SYSGEN OPTIONS 


sf FCS LIBRARY OPTIONS .... +6 «© © © «© «© «© © © «© « Ko 
e 2 e FCTYP se e es s e s ee s s id = e * e e s e e e se s e K- 


INDEX Index-l 


FIGURES 


FIGURE File-Access Operation ... « «6 «© « © «© «© © © @ » 
Record I/O Operations .. ese. ge 
Single Buffering Versus Multiple Buffering ee ees 
Directory Structure for Single-User Volumes ... 


1-1 
1-2 
1-3 
5-1 
5-2 Directory Structure for Multiuser Volumes .... 
6-1 
6-2 
6-3 
7-1 


OV 01 U1 Et 
1 of 
WO~ID ND WD ~] WF 


Data Flow During Command Line Processing ..... 
Format of Switch Descriptor Table Entry .... 
Format of Switch Value Descriptor Table Entry . 
Processing Steps Required to Generate a Parser 
Program Using TPARS . .. «+» «© © » © © «© «© © «© 713 
7-2 Flow of Control When TPARS Is Called from an 


OV OV 
iol 
NN 


Executing User Program . . .« « »« «© © «© « «© © « « 714 
A-1l File Descriptor Block Format ....... +... A~2 
B-1l Filename Block Format: «. 6 2. «© 4 se & 0 se » BB 
B-2 ANSI Filename Block Format ... . ee ph te ee, BS 
G-1l ANSI Magnetic Tape File Header Block (FCS 

Compatible) « 3 « < s « © © © © «© * «# 


° e ° e ° ° G-9 
H-1 Statistics Block Format e 2 2 s e 2 e 2 2 2 2 * . H 1 


viii 


WN 
1 
ee) 


IED 
WHE HH 


PE ee ee 
NE BWNH Hee 


AAQAANAANDAANA 


CONTENTS 
Page 


TABLES 


Shared Pile Access. 2. ‘s--s- e: « -«. “a 4. we we ere en wwe od 
Macro Calls Generating FDB Information . ..... 2- 
File Access Privileges Resulting from OPENSx 

Maero: Cakl: a5 ow. 3. a Se ee See OS en RS SOR RD Sa er ew: Sd a, ES 
R2 Control Bits for .EXTND Routine ....... 4-23 
PDB .OLFSet: Definitions: .<: 6. 6. a: et! ese at WS! ee oe 
Filename Block Offset Definitions .... 
Filename Block Status Word (N.STAT) ... 
Filename Block Offset Definitions for ANSI 
Magnetic Tape ....e.e. a ee ee ee oe ae ee 
Summary of I/O-Related System Directives s 
Home--Block Format - %. 4 vs, «+s Ge @. 6 ewe oe we 
Fide- Header BLOCK: --6.- ioe: vst wm, Oe wh le OS a. ke oe 
Volume Label Format ...+. +. « e« «© © © «© © @ » 
File Header Label -(HDRI)-«. .:-0 «6 ©. @ %- Sw ew w 
File Header Format (HDR2) er ae ee ee ee ee ee ee 
File-Header Label (HDR3) .~. . « « « « © « «© «© « «© «@ 
FCS Library Descriptions . . « « « « » «© © «© «© «© « 
-FCTYP Values: 4. 40 0 See ew ee we we ae. 


CARE cor ta err a as a 
NE OAU PRP WP 


ix 


PREFACE 


MANUAL OBJECTIVES 


The purpose of this manual is to familiarize the users of an RSX-11M, 
RSX-11M-PLUS, or IAS operating system with the File Control Services 
(FCS) facility provided with the system. 


INTENDED AUDIENCE 


Since the file control services described herein pertain to both 
MACRO-11 and FORTRAN programs, the reader is assumed to be familiar 
with the manuals describing these program development tools. Also, 
since the development of programs in an RSX-11 or IAS environment 
necessarily involves the use of the Task Builder, the reader is also 
assumed to be familiar with this system program. 


STRUCTURE OF THE DOCUMENT 


Chapter 1 briefly describes the FCS features available for IAS/RSX-11 
users and defines some of the terminology that is pertinent to 
discussions throughout the manual. This chapter is vital to 
understanding the balance of the manual. 


Chapter 2, perhaps the most important in the manual, describes’ the 
actions you must take at assembly time to prepare adequately for all 
intended file I/O processing through FCS. This chapter describes’ the 
data structures and working storage areas that you must define within 
a particular program in order to use any of the file control services 
provided by the system. Unless you are thoroughly familiar with the 
content of this chapter, you are advised to defer a reading of 
subsequent chapters, since all that follows is dependent upon a 
complete working understanding of the material in Chapter 2. 


Chapter 3 describes the run-time macro calls that allow you _ to 
manipulate files and to perform I/O operations. 


Chapter 4 describes a set of run-time routines used to perform 
functions related to controlling files, such as reading and writing 
directory entries, renaming or extending files, and so forth. 


Chapter 5 describes the structure of files supported by the IAS and 
RSX-11 systems. In this context, the structure of files for disks, 
DECtapes, and magnetic tapes are covered. 


Chapter 6 describes two collections of object library routines called 
the Get Command Line (GCML) routine and the Command String Interpreter 
(CSI). These routines may be linked with the user task to perform 
operations associated with the dynamic input of command lines. Such 
input consists of file specifications that identify and control the 
files to be processed by the user program. 


Chapter 7 describes the Table-Driven Parser (TPARS), which provides 


Xi 
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you with the means to define and parse command lines in a unique 
user-designed syntax. 


Chapter 8 describes the queuing of files for printing. This facility 
is available at both the MACRO and subroutine levels. 


Finally, a number of appendixes are provided that supply detailed 
information of further interest. Appendix A and Appendix B outline in 
detail the File Descriptor Block (FDB) and the filename block, 
respectively, two structures forming a significant part of the 
descriptive material in Chapter 2. Appendix C summarizes a number of 
I/O-related system directives that form a part of the total resource 
management capabilities of the RSX-11 or the IAS Executive. Through 
simplified sample programs, Appendix D illustrates the use of the 
IMacro calls that create and initialize the FDB. These sample programs 
also include some of the macro calls that are used for processing 
files. 


Appendix E illustrates the structure of the index file of a Files-ll 
volume, while Appendix F describes in detail the format and content of 
a file header block. The format and content of magnetic tape labels 
are similarly described in Appendix G. The format and content of the 
statistics block are described in Appendix H. 


The error codes returned by the system are listed in Appendix I, and 
field-size symbols are listed in Appendix J. 


Appendix K lists RSX-11M/M-PLUS FCS library SYSGEN options, including 
a brief description of each. 


ASSOCIATED DOCUMENTS 


Other manuals closely allied to the purposes of this document are 
described briefly in either the RSX-11M or RSX-11M-PLUS Information 
Directory and Index. The information directories define the intended 


readership of each manual in the appropriate set and provide a brief 
synopsis of each manual's contents. 


CONVENTIONS USED IN THIS DOCUMENT 


Unless otherwise noted, the term "RSX-11" refers to both RSX-11M and 
RSX-11M-PLUS. 
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SUMMARY OF TECHNICAL CHANGES 


This revision of the IAS/RSX I/O Operations Reference Manual contains 


changes and additions relative to the following: 


Ls 


New FCS functions: 


CLOSES - Truncates the file by default 
REWIND - .POINT and .CTRL clear EOF condition 


PUTS - Magtape enhancement 


ANSI magtape level 3 compliance (See Appendix G): 


An 


The magnetic tape ACP now supports the ANSI header labels. 


The magnetic tape ACP now supports 17-character file names 
that include ANSI "a" characters. 


overlayed FCS resident library (FCSRES). 


Support for unlabeled tape (See Appendix G). 


The following changes to CSI1 and CSI2 (See Chapter 6): 


The file name and extension may be replaced by a quoted 
string. 


The device name may be logical queue name (PRINT:, BATCH:, 
etc.). 


The file name may contain any combination of wildcards 
(A*BSC*,T*). 


Quotes may not be used as switch values without quoting 
them. 


The version number is not completely validated. 


The directory specification is validated by rules similar 
to those used in VMS. 


Longword number conversion is now supported, resulting in 
two words of number stored when two words are requested. 


Big buffer support (See Chapter 1). 


Multibuffering (See Chapter 1). 
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CHAPTER 1 


FILE CONTROL SERVICES 


IAS and RSX-11 File Control Services (FCS) enable you to. perform 
record-oriented and block-oriented I/O operations, and to perform 
additional functions required for file control, such aS open, close, 
wait, and delete operations. To invoke FCS functions, you issue macro 
calls to specify desired file control operations. The FCS macros are 
called at assembly time to generate code for specified functions and 
operations. The macro calls provide the system-level, file control 
primitives with the necessary parameters to perform the file access 
operations that you request (see Figure 1-1). 


FCS is basically a set of routines that are linked with the user 
Program at task-build time from a system global area (IAS) or resident 
system library (RSX-11), or a system object module library. These 
routines, consisting of pure, position-independent code, provide an 
interface to the file system, enabling you to read and write files on 
file-structured devices and to process files in terms of logical 
records. 


Logical records are regarded by your program as data units that are 
structured in accordance with application requirements, rather than as 
physical blocks of data on a particular storage medium. 


FCS provides the capability to write a collection of data (consisting 
of distinct logical records) to a file in a way that enables the data 
to be retrieved at will. You can retrieve data from the file without 
having to know the exact format in which it was written to the file. 


FCS, therefore, is transparent to the user, so that records can be 
read or written in logical units that are consistent with particular 
application requirements. 


USER-ISSUED MACRO CALL 
FILE CONTROL SERVICES 


FILE CONTROL PRIMITIVES 


PERIPHERAL DEVICE HARDWARE 
_ (e.g., disk, VTO5) 
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Figure 1-1 File-Access Operation 


Led 


FCS provides an extensive set of macros to simplify your interface to 
the system's I/0 facilities. In addition to generating calls to FCS 
subroutines, these macros create and maintain certain data structures 
that are required when performing any file I/O operations. The 
required data structures include the following: 


1. A File Descriptor Block (FDB) that contains information 
necessary at execution time for processing the file. 


2. A dataset descriptor that is accessed by FCS to obtain ASCII 
file name information required when opening a specified file. 


3. A default filename block that is accessed by FCS to obtain 
default file name information required when opening a 
specified file. This data structure is accessed when 
complete file information is not specified in the dataset 
descriptor. 


4. A file storage region (FSR) that is used by FCS for working 
storage. 


The FDB is described in detail in Appendix A and Appendix B. The 
dataset descriptor and the default filename block are described in 
detail in Section 2.4. The FSR is described in Section 1.2. 


1.1 FILE ACCESS METHODS 


IAS and RSX-11 support both sequential and random access to data in 
files on sequential access devices (such as magnetic tapes and card 
readers) and random access devices (such as_ disks). The sequential 
access method is device independent; that is, sequential access can 
be used for both record-oriented and random access devices (for 
example, card reader and disk, respectively). You can use the random 
access method only for random access devices. 


1.2 FILE STORAGE REGION (FSR) 


The file storage region (FSR) is an area allocated in your program as 
working storage for performing record I/0 operations (see Section 
1.5). The FSR consists of two program sections that are always 
contiguous to each other. These program sections exist for the 
following purposes: 


SSFSR1 - This area of the FSR contains the block buffers and the 
block buffer headers for record I/O processing. You 
determine the size of this area at assembly time by 
issuing the FSRSZS$ macro call (see Section 2.6.1). The 
number of block buffers and associated headers is based 
on the number of files that you intend to open 
simultaneously for record I/O operations. 


SSFSR2 - This area of the FSR contains impure data that is used 
and maintained by FCS when performing both record and 
block I/0 operations. Portions of this area are 
initialized at task-build time, whereas other portions 
are maintained by FCS. 
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The size of the FSR can be changed, if desired, at task-build time. 
Section 2.7 presents the procedures that provide you with this 
flexibility. 


The data flow during record I/O operations is depicted in Figure 1-2. 
Note that blocks of data are transferred directly between the FSR 
block buffer and the device containing the desired file. The 
deblocking of records during input is accomplished in the FSR block 
buffer, and the blocking of records is similarly accomplished in the 
FSR block buffer during output. Note also that FCS serves as your 
interface to the FSR-block-buffer pool. All record I/0 operations, 
which are initiated through GETS and PUTS macro calls, are totally 
synchronized by FCS uniess muitibuffering is in uSe. 


Record I/O operations are described in detail in Section 1.5. 


BLOCK 
BUFFER 
POOL 
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Figure 1-2 Record I/O Operations 


1.3 DATA FORMATS FOR FILE-STRUCTURED DEVICES 


Data is transferred between peripheral devices and memory in blocks. 
A data file consists of virtual blocks, each of which may contain one 
or more logical records created by your program. In FCS terms, a 
virtual block in a file consists of 512(decimal) bytes for random 
access devices. The size of the logical records in the virtual blocks 
is under the control of the user program that originally wrote the 
records. 


When creating a new file, your program can specify that the records in 
the file need not all be the same size. Such records are known as 


variable-length records. Conversely, if your program indicates’ that 
all records in the new file will be equal in size, the records are 
known as fixed length. 


There are two types of variable-length records: sequenced and 
nonsequenced. Both must be word aligned. Sequenced variable-length 
records are preceded by a 2-word record header. The first word 
contains the length of the record, and the second word contains the 
value of the sequence number: 


16 16 


Byte Count Sequence Number 


Nonsequenced variable-length records are preceded by a_ single-word 
record header containing the length of the record: 


n-2 bytes of data 


16 


Byte Count 


Both fixed- and variable-length records are aligned on a word 
boundary. Any extra byte that results from an odd-length record is 
simply ignored. (The extra byte is not necessarily a 0 byte.) 


n bytes of data 


Virtual blocks and logical records within a file are numbered 
sequentially, each starting at 1. A virtual block number is a file 
relative value, whereas a logical block number is a volume relative 
value. Ordinarily, records may cross block boundaries. This means 
that the beginning of a record can fill out the end of a block, while 
the rest of the record occupies the beginning of the next block. 


1.3.1 Data Formats for ANSI Magtape 


You can use both fixed- and variable-length records on magtape; their 
format conforms to the ANSI standard. 


On magtape, a virtual block corresponds to! a “physical ‘1ecor 

default length of a block is 512 bytes. Its length can be changed to 
any value greater than 8 bytes (14 bytes for a write function) and up 
to 2048 bytes with the use of the FDBF$ macro (see Section 2.2.1.6). 
Records are not allowed, to cross biock boundaries. a. 


Fixed-length records are packed into a block with no control 
information and no padding for alignment. The block is, Atuaiba ted ®so 
that it ends at the word boundary following the end of ‘the last record 
that will fit in the block buffer. 


Variable-length.. record& are preceded by a 4-byte connt.... fieldg« 
expressed in decimal in ASCII characters. The count includes the 
length of the record and the 4-byte count field. After the last 
record in a block (if there is any space left in the block), a caret 
character ("“", ASCII code 136), which appears where the next byte 
count should be, signals the end of data in that block. 
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1.4 BLOCK I/O OPERATIONS 


The READS and WRITES macro calls (see Sections 3.15 and 3.16, 
respectively) allow the user to read and write virtual blocks of data 
from and to a file without regard to logical records within the file. 
Block I/O operations provide an efficient means of processing file 
data, since such operations do not involve the blocking and deblocking 
of records within the file. Also, in block I/O operations, you can 
read or write files in an aSynchronous manner; that is, control may 
be returned to your program before the requested I/O operation is 
completed. 


When block I/O is used, the number of the virtual block to be 
processed is specified as a parameter in the appropriate READS/WRITES 
macro call; the virtual blocks so specified are processed directly in 
a reserved buffer in user memory space. READS and WRITES can be used 
only on block-structured devices. 


As implied above, you are responsible for synchronizing all block I/0 
operations. Such asynchronous operations can be coordinated through 
an event flag (see Section 2.8.1) specified in the READS/WRITES$ macro 
call. The system uses the event flag to signal the completion of a 
specified block I/O transfer, enabling you to coordinate those _ block 
I/O operations that are dependent on each other. 


1.5 RECORD I/O OPERATIONS 


The GETS and PUTS macro calls (see Sections 3.9 and ss 
respectively) are provided for processing individual user records in 
files. Using the FSR block buffers (see Section 1.2), the GETS and 
PUTS routines perform the necessary blocking and deblocking of records 
within the virtual blocks of the file, allowing your program to access 
logical records. 


Sequential access mode I/O operations can be performed for both fixed- 
and variable-length records. Random access mode I/O operations can be 


performed only for fixed-length records. Your program accesses 
records randomly by specifying a record number. This number 
represents the _ position of the desired record within the 
file -- viewing the file as an array of fixed-sized records, with the 


number 1 representing the first record physically present in the file 
and n_ the last. Successive GETS or PUTS operations in random access 
mode can access records anywhere within the file. To do so, your 
program need only modify the record number specified as part of the 
random record operation. After each such random operation, FCS 
increments the record number used in the operation. If your program 
does not again modify this number prior to issuing another’ record 
operation, the record actually accessed is the next sequential record 
in the file. 


In contrast to block I/O operations, all record I/O operations are 
synchronous; that is, control is returned to your program only after 
the requested I/O operation is completed. 


Because GETS/PUTS operations process logical records within a virtual 
block, only a limited number of GETS or PUTS operations result in an 
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actual I/O transfer (for example, when the end of a data block is 
encountered). Therefore, all GETS/PUTS I/O requests do not 
necessarily involve an actual physical transfer of data. 


1.6 DATA~TRANSFER MODES 


When record I/O is used, a program can gain access to a record in 
either of two ways after the virtual block has been transferred into 
the FSR from a file: 


1. In move mode, by specifying that individual records are to be 
moved from the FSR block buffer to a user-defined record 
buffer (see Figure 1-2) 


2. In locate mode, by referencing a location in the File 
Descriptor Block (see Section 1.9) that contains a pointer to 
the desired record within the FSR block buffer 


1.6.1 Move Mode 


Move mode requires that data be moved between the FSR block buffer and 
a user-defined record buffer. For input, data is first read into the 
FSR block buffer from a peripheral device and then moved to your 
record buffer for processing. For output, your program first builds a 
record in the user record buffer; FCS then moves the record to the 
FSR block buffer, from which it is written to a peripheral device when 
the entire block is filled. 


Move mode Simulates the reading of a record directly into your’ record 
buffer, thereby making the blocking and deblocking of records 
transparent to you. 


1.6.2 Locate Mode 


Locate mode enables your to access records directly in the FSR _ block 
buffer. Consequently, there is normally no need to transfer data from 
the FSR block buffer to your record buffer. To access records 
directly in the FSR block buffer, you refer to locations in the File 
Descriptor Block (see Section 1.9) that contain values defining the 
length and the address of the desired record within the FSR block 
buffer. These values are present in the FDB aS a result of FCS macro 
calls that you issued. 


Program overhead is reduced in locate mode, since records can be 
processed directly within the FSR block buffer. Moving data to the 
user record buffer in locate mode is required only when the last 
record of a virtual block crosses block boundaries. 


1.7 MULTIPLE BUFFERING FOR RECORD I/O 


By supporting multiple buffers for record I/0, FCS provides the 
capability for users who select multibuffered FCS (see Appendix K) to 
read data into buffers in anticipation of user program requirements, 
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and to write the contents of buffers while the user program is 
building records for output. You can thus’ overlap the internal 
processing of data with file I/O operations, as illustrated in Figure 
1-3. 


When read-ahead multiple buffering is used, the file must be 
sequentially accessed to derive full benefit from multiple buffering. 
For write-behind multiple buffering, you can use any file access 
method with full benefit. 


When multiple buffering is used, you must allocate sufficient space in 
the FSR for the total number of block buffers in use at any given 
time. The FSRSZ$ macro call (see Section 2.6.1) is used to accomplish 
the allocation of space for FSR block buffers. 


Time a eee ee 


Sinale process record | write record process record write record coe 
Buffer 


Multiple process record | write record process record | write record 
Buffer | process record | write record | process record | 
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Figure 1-3 Single Buffering Versus Multiple Buffering 


Multiple buffering can improve performance for I/O-bound tasks under 
certain circumstances. 


For example, consider an I/O bound task running as the dedicated or 
highest priority application on a system. For such a task, multiple 
buffering can decrease execution time by enabling overlap of I/O and 
task execution. If the task uses large records or operates on 
clusters of records, big buffering is also advantageous. This assumes 
that it is reasonable to use more task address space and physical 
memory for increased buffer space, and more pool for the increased 
number of outstanding I/O packets. 


However, if other tasks run at the same priority as that of the 
application task described above, then an overlap of I/O and task 
execution is already achieved among these tasks without multiple 
buffering. In this case, multiple buffering would use up address 
Space and pool without improving execution speed. If virtual and 
physical address space is available, big buffering would improve 
performance. 


Big buffering reduces the number of disk accesses by allowing 
multiblock input and output. Normally, the disk accesses for GETS or 
PUTS operations are performed one sector at a_ time. Using FCS big 
buffers allows you to read or write a specified number of sectors in a 
single operation. 
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To use big buffers, you must select the buffer size and specify that 
buffer size in the parameter lists for each occurrence of both the 
FSRSZ$ macro and the FDBDFS$ macro in your program. 


You should choose a buffer size that is a multiple of 512(decimal) 
bytes, the size of one disk block. Since the default amount allocated 
by a file extend is five blocks and disks often contain many 5-block 
files or parts of files, a buffer size of five blocks is generally a 
good choice. Larger amounts may increase performance, but note that 
you are trading large amounts of memory for speed. 


You must reserve the buffer space in your program and you must make 
the buffer size known to the FDB. The FSRSZ$ macro allows you to 
specify the total buffer space needed. Specify 512(decimal) bytes for 
each normal disk file, plus the buffer size that you have selected for 
each big buffered file. For example, assume that a program has’ three 
files: one normal file (512-byte buffer); one file with a big buffer 
Size of three blocks; and one file with a big buffer size of five 
blocks. The following call to the FSRSZ$ macro reserves the space 
properly: 


In the FDB of each file that has a big buffer, you must override the 
default buffer size, using either the FDBFSA macro or the FDBFSR 
macro. For a file with five bloc! 


macro call is: 
FDBFSA <5*512.> 


On RSX-11M-PLUS systems, the SYSLIB provided as the default library 
contains all the proper FCS modules for big buffer support. RSX-11M 


ee ee Ook. er er; a a eee ek, meee 
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1.8 SHARED ACCESS TO FILES 


Files-l1l permits shared access to files according to established 
conventions. You can issue two macro calls, among several available 
in FCS for opening files, to invoke these conventions. The OPNSSx 
macro call (see Section 3.2) is used specifically to open a file for 
shared access. The OPENSx macro call (see Section 3.1), on the other 
hand, invokes generalized open functions that have shared-access 
implications only in relation to other I/O requests then issued. Both 
Macro calls take an alphabetic suffix that specifies the type of 
operation being requested for the file, as follows: 


R - Read existing file. 


W Write (create) a new file. 
M - Modify existing file without extending its length. 
U - Update existing file and extend its length, if necessary. 
A - Append data to end of existing file. 
The suffix R applies to the reading of a file, whereas the suffixes W, 


M, U, and A all apply to the writing of a file. These macro calis and 
the shared access conditions that they invoke are summarized below. 


1-8 
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You can use the OPNSSx and OPENSx macro calls as follows for shared 
access to files: 


1. When the OPNSSR macro call is issued, read access to the file 
is granted unconditionally, regardless of the presence of one 
or more concurrent write access requests to the file. (The 
OPNSSR macro call permits concurrent write accesses to the 
file while it is being read.) Subsequent write access 
requests for this same file are honored. Thus, several 
active read access requests and one or more write access 
requests may be present for the same file. However, multiple 
tasks simultaneously accessing the file for write operations 
are subject to certain restrictions, as detailed in point 2. 


2. While FCS allows concurrent write access requests through the 
use of the OPNSSW, OPNSSM, OPNSSU, and OPNSSA macro, 
synchronizing access to the file is the responsibility of the 
user tasks themselves. To avoid the retrieval or storage of 
inconsistent data, each such task must implement and use some 
user-defined mechanism that ensures that the file is accessed 
in a serial fashion. 


3. When the OPENSR macro call is issued, read access to the file 
is granted, provided that no write access requests for that 
file are active. (The OPENSR macro call does not permit 
concurrent write access to the file while it is being read.) 


Note from the above that readers of a shared file should be aware that 
the file may yield inconsistent data from request to request if that 
file is also being written. 


Shared access during reading does not necessarily mean that the access 
requests are all from separate tasks. A file could also be shared by 
a Single task that has opened the file on several different logical 
unit numbers. 


Table 1-1 shows the circumstances under which Files-ll permits a 
second file access when the file is opened for shared access. 


Table 1-1 
Shared File Access 


Second Access 
Shared read Shared write 


Read Yes Yes No 


Shared 
Read 


Write 


Shared 
Write 


19 
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1.9 FILE DESCRIPTOR BLOCK (FDB) 


The File Descriptor Block (FDB) contains information used by FCS in 
opening and processing files. One FDB is required for each file that 
is to be opened simultaneously by your program. You initialize some 
portions of the FDB with assembly-time or run-time macro calls, and 
FCS maintains other portions. Each FDB has five sections that contain 
user- or system-initialized information: 


e File attribute section 

e Record or block access section 

e File open section 

e Block Buffer Section 

e Filename block portion of the FDB 


The information stored in the FDB depends upon the characteristics of 
the file to be processed. The FDB and the macro calls that cause 
values to be stored in this structure are described in detail in 
Section 2.2. Appendix A describes in detail the format and the 
content of the FDB. 


1.10 DATASET DESCRIPTOR AND DEFAULT FILENAME BLOCK 


Normally, either a dataset descriptor or a default filename block is 
specified for each file that you intend to open. These data 
structures provide FCS with the file specifications required for 
opening a file. Although either one or the other is usually defined, 
both can be specified for the same file. The dataset descriptor and 
the default filename block are summarized below and described in 
detail in Sections 2.4.1 and 2.4.2, respectively. 


When a file is being opened using information already present in the 
filename block, neither the dataset descriptor nor the default 
filename block is accessed by FCS for required file information. This 
method of file access, which is termed "opening a file by file ID," is 
an efficient means of opening files. Section 2.5 describes this 
process in detail. 


1.11 KEY TERMS USED THROUGHOUT THIS MANUAL 


Listed below are terms used throughout this manual that have specific 
meanings in the context of FCS operations. 


FILE DESCRIPTOR BLOCK (FDB) 

The tabular data structure that provides FCS with information 
needed to perform I/O operations on a file. The space for this 
data structure is allocated in your program by issuing the FDBDFS$ 
macro call (see Section 2.2.1.1). Each file to be opened 
Simultaneously by your program must have an associated FDB. 
Portions of the FDB are user defined and others are maintained by 
FCS. Assembly-time or run-time macro calls are provided for you 
in order to initialize the FDB. The format and content of the 
FDB are detailed in Appendix A. 
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FILENAME BLOCK 


The portion of the FDB that contains the various elements of a 
file specification (that is, directory, file name, file type, 
file version number, device, and unit) for use by the FCS 
file-processing routines. Initially, as a file is opened, FCS 
fills in the filename block with user-specified information taken 
from the dataset descriptor and/or the default filename block 
(see below). The methods of creating file specifications for 
initializing the filename block are described in detail in 
Section 2.4; the format and content of the filename block itself 
are described in Appendix B. 


ULT FILENAME BLOCK 
The default filename block, an area allocated within your program 
by issuing the NMBLKS macro call (see Section 2.4.2), contains 
the various elements of a file specification. The default 
filename block is a user-created structure, whereas the filename 
block within the FDB is maintained by FCS. You create the 
default filename block to supply file specifications to FCS that 
are not otherwise available through the dataset descriptor (see 
below). In other words, from information defined in the default 
filename block, FCS creates a parallel structure in the FDB that 
serves as the execution time repository for information that FCS 
requires in opening and operating on files. 


Thus, the terms "default filename block" and "filename block" 
refer to separate and distinct data structures. These 
distinctions should be kept clearly in mind whenever these terms 
appear in the manual. Though created and used differently, these 
areas are structurally identical. 


DATASET DESCRIPTOR 


The dataset descriptor is a 6-word block in your’ program 
containing the sizes and the addresses of ASCII data strings that 
together constitute a file specification (see below). This data 
Structure, which you also create, is described in detail in 
Section 2.4.1. Unless the filename block in the FDB has_ been 
initialized, dataset-descriptor and/or default filename block 
information must be provided to FCS before the specified file can 
be opened. 


DATASET-DESCRIPTOR POINTER 


FILE 


FILE 


An address value that points to the 6-word dataset descriptor 
within your program. This address value is stored in the FDB, 
allowing FCS to access a user-created file specification in the 
dataset descriptor. 


SPECIFICATION 

Any system or user program having a requirement to refer to files 
does so through a file specification. Such information names a 
file and allows it to be explicitly referenced by any task. A 
file specification, whether for input or output, contains 
specific information that must be made available to FCS before 
that file can be opened. The term "file specifier" is sometimes 
used as a synonym for "file specification." 


STORAGE REGION (FSR) 

The file storage region (see Section 1.2) is an area of memory 
that you reserve for use in I/O operations. You can allocate 
this area by issuing the FSRSZ$ macro call in your program (see 
Section 2.6.1). 
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SYSTEM CHARACTERISTICS 


Listed below are the important characteristics of FCS that are 
important in using its I/O facilities: 


READS/WRITES operations are asynchronous; you are responsible 
for coordinating all block I/O activity. In contrast, 
GETS$/PUT$ operations are synchronized entirely by FCS; 
control is not returned to your program until the requested 
GETS/PUTS operation is completed. 


FCS macro calls save and restore all registers, with the 
following exceptions: 


1. The file-processing macro calls (see Chapter 3) place _ the 
FDB address in RO. 


2. Many of the file control routines (see Chapter 4) return 
requested information in the general registers. 


The FDBDF$ macro call (see Section 2.2.1.1) is issued to 
allocate space for an _ FDB. Once the FDB is allocated, 
necessary information can be placed in this data construct 
through any logical combination of assembly-time and/or 
run-time macro calls (see Sections 262k and 2a2u2; 
respectively). Certain information must be present in the FDB 
before FCS can open and operate on a Specified file. 


For each assembly-time FDB initalization macro call, a 
corresponding run-time macro call is provided that supplies 
identical information. Although both sets of macro calls (see 
Table 2-1) place the same information in the FDB, each set 
does so in a different way. The assembly-time calls generate 
»-BYTE or .WORD directives that create specific data, while the 
run-time calls generate MOV or MOVB instructions that place 
desired information in the FDB during program execution. 

if, man; - Serres aitic a during any of the 
file-processing operations deseribed in Chapter 3, or during 
the execution of several of the file control routines (see 
Section 4.1), the C-bit (carry condition code) in the 
Processor Status Word is set, and an error indicator is 
returned to FDB offset location F.ERR. 


NOTE 


When I/O is being done using the READS/WRITE macros, 
the IOSB parameter must be specified for F.ERR and the 
C-bit to be properly returned (see Section 3.15). 


If the address of a user-coded, error-handling routine is specified as 


a 


parameter in any of the file-processing macro calls, a JSR PC 


instruction to the error-handling routine is generated. The routine 
is then executed if the C-bit in the Processor Status Word is set. 
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PREPARING FOR I/0 


The MACRO-11 programmer must establish the proper data base and 
working storage areas within the particular program in order to 
perform input/output operations. The following actions must be 
performed: 


e Define a File Descriptor Block (FDB) for each file that is to 
be opened simultaneously by your program (see Section 2.2). 


e Define a dataset descriptor and/or a default filename block 
(see Sections 2.4.1 or 2.4.2, respectively) if you intend to 
access these structures to provide required file 
specifications to FCS. 


e Establish a file storage region (FSR) within the program (see 
Section 2.6). (The initialization procedures for FORTRAN 
tasks are described in detail in the FORTRAN-IV User's Guide 
and the FORTRAN-IV-PLUS User's Guide.) 


This chapter describes the macro calls that must be invoked to provide 
the necessary file-processing information for the FDB. Such 
information is placed in the FDB in one of three ways: 


1. By the assembly-time FDB initialization macro calls (see 
Section 2.2.1) 


2. By the run-time FDB initialization macro calls (see Section 
2.2.2) 


3. By the file-processing macro calls (see Chapter 3) 


Data supplied during the assembly of the source program establishes 
the initial values in the FDB. Data supplied at run time can either 
initialize additional portions of the FDB or change values established 
at assembly time. Similarly, the data supplied through the 
file-processing macro calls can either initialize portions of the FDB 
or change previously initialized values. 


Table 2-1 lists the macro calls that generate FDB information. 


Table 2-1 
Macro Calls Generating FDB Information 


Assembly Time FDB Run-Time FDB File-Processing 
Macro Calls Macro Calls Macro Calls 


FDBDF$ (Required) FDATSR OPENS (all variations) 
FDATSA FDRCSR CLOSES 
FDRCSA FDBKSR GETS (all variations) 


FDBKSA FDOPSR PUTS (all variations) 
FDOPSA FDBFSR READS 
FDBFSA WRITES 

DELETS 

WAITS 


2.1 .MCALL DIRECTIVE - LISTING NAMES OF REQUIRED MACRO DEFINITIONS 


All the assembly-time, run-time, and file-processing macro calls (see 
Table 2-1 above) that you intend to issue in a program must first be 
listed as arguments in an .MCALL directive. Doing so allows’ the 
required macro definitions to be read in from the system macro library 
during assembly. 


The .MCALL directive and associated arguments must appear in the 
program prior to the issuance of any macro call in the execution code 
of the program. If the list of macro names is lengthy, several .MCALL 
directives, each appearing on a separate source line, must be 
specified to accommodate the entire list of macro names. The number 
of such names that may appear in any given .MCALL statement is limited 
only by the availability of space within that 80-byte source line. 


The .MCALL directive takes the following general form: 
-MCALL argl,arg2,...,argn 
argl,arg2,...,argn 


A list of symbolic names identifying the macro definitions 
required in the assembly of your program. If more than one 
source line is required to list the names of all desired macros, 
each additional line so required must begin with an .MCALL 
directive. 


For clarity of functional use, the assembly-time, run-time, and 
file-processing macro names may be listed in each of three 
separate .MCALL statements. The macro names may also be _ listed 
alphabetically for readability, or they may be intermixed, 
regardless of functional use. All these options are matters of 
preference and have no effect whatever on retrieving macro 
definitions from the system macro library. 


For those users planning to invoke the command line processing 
capabilities of the Get Command Line (GCML) routine and the 
Command String Interpreter (CSI), all the names of the associated 
macroS muSt also be listed as arguments in an .MCALL directive. 
GCML and CSI, ordinarily employed in system or application 
programs for convenience in dynamically processing file 
specifications, are described in detail in Chapter 6. 
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The .MCALL directive is described in detail in the PDP-11 MACRO-11 
Language Reference Manual. The sample programs in Appendix D also 
illustrate the use of the .MCALL directive. Note that these 
directives appear as the first statements in the preparatory coding of 
these programs. 


The object routines described in Chapter 4 should not be confused with 
the macro definitions available from the system macro library. The 
file control routines, constituting a body of object modules, are 
linked into your program at task-build time from the system object 
library ({1,1]SYSLIB.OLB). You should consult Section 4.1 for a 
description of these routines. 


The following statements are representative of the use of the .MCALL 
directive: 


-MCALL FDBDFS$,FDATSA,FDRCSA,FDOPSA,NMBLKS,FSRSZS$,FINITS 
»-MCALL OPENSR,OPENSW,GETS, PUTS$,CLOSES 


NOTE 


You can use the macro FCSMCS to declare 
in the .MCALL format the most commonly 
used FCS macros, as follows: 


~-MCALL FCSMCS 
FCSMCS 


FCS macros declared in this manner 
include: OPENSx, OPNSSx, CLOSES, READS, 
WRITES, WAITS, GETS, PUTS, DELETS, 
FINITS, FSRSZS, FDBDFS, FDATSx, FDRCSx, 
FCOPSx, FDBFSx, FDBKS$x;, and NMBLKS. Le 
other macros are required, explicit 
-MCALLS must be issued. A disadvantage 
of using this method to declare .MCALL 
macros is that unused macros may take up 
possibly critical assembler symbol table 
Space, thus slowing down the assembly 
process. 


2.2 FILE DESCRIPTOR BLOCK (FDB) 


The File Descriptor Block (FDB) is the data structure that provides 
the information needed by FCS for all file I/O operations. Two sets 
of macro calls are available for FDB initialization: one set is used 
for assembly-time initialization (see next section), and the other set 
is used for run-time initialization (see Section 2.2.2). Run-time 
macros are used to supplement and/or override information specified 
during assembly. Appendixes A and B illustrate all the sections of 
the FDB in detail. 


2.2.1 Assembly-Time FDB Initialization Macros 


Assembly-time initialization requires that the FDBDF$ macro call be 
issued (see Section 2.2.1.1) to allocate space for and to define the 
beginning address of the FDB. Additional macro calls can then be 
issued to establish other required information in this structure. 
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The assembly-time macros that accomplish these functions are described 
in the following sections. These macro calls take the general form 
shown below: 


mcnamS$A pl,p2,...,pn 
mcnamSA 


The symbolic name of the macro. 


pl,p2,...,pn 


The string of initialization parameters associated with the 
specified macro. A parameter may be omitted from the string by 
leaving its field between delimiting commas null. Assume, for 
example, that a macro call may take the following parameters: 


FDOPSA 2,DSPT,DFNB 


Assume further that the second parameter field is to be coded as 
a null specification. In this case, the statement is coded as 
follows: 


FDOPSA 2,,DFNB 


Also, a trailing comma need not be inserted to reflect the 
omission of a parameter beyond the iast explicit specification. 
For example, the macro call 


FDOPSA 2,DSPT,DFNB 
need not be specified as 
FDOPSA 2,DSPT, 


if the last parameter (DFNB) is omitted. Rather, such a macro 
call is specified as follows: 


FDOPSA 2,DSPT 


If any parameter is not specified, that is, if any field in the macro 
call contains a null specification, the corresponding cell in the FDB 
is not initialized and thus remains 0. 


Multiple values may be specified in a parameter field of certain macro 
calis. Such values are indicated by placing an exclamation point (!) 
between the values, indicating a logical OR operation to the MACRO-11 
assembler. Using multiple values in this manner is pointed out in 
this manual where such specifications apply. 


Throughout the descriptions of the assembly-time macros in _ the 
following sections and elsewhere in this manual, symbols of the form 
F.xxXxX or F.xxxx are referenced (for example, F.RTYP). These symbols 
are defined as offsets from the beginning address of the FDB, allowing 
specific locations within the FDB to be referenced. Thus, you can 
reference or modify information within the FDB without having to 
calculate word or byte offsets to specific locations. 


Using such symbols in system/user software has the additional 
advantage of permitting the relative position of cells within the FDB 
to be changed (in a subsequent release, for example) without affecting 
your current programs or the coding style employed in developing new 
programs. 
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2.2.1.1 FDBDFS$ - Allocate File Descriptor Block (FDB) - The FDBDFS 
macro call is specified in a MACRO-11 program to allocate space within 
the program for an FDB. This macro call must be specified in the 
source program once for each input or output file to be opened 
Simultaneously by your program in the course of execution. Any 
associated assembly-time macro calls (see Sections 2.2.1.2 through 
2.2.1.6) must then be specified immediately following the FDBDF$ macro 
if you desire to accomplish the initialization of certain portions of 
this FDB during assembly. 


The FDB allocation macro takes the following form: 
label: FDBDFS$ 
label 


A user-specified symbol that names this particular FDB_ and 
defines its beginning address. This label has particular 
significance in all I/O operations that require access to_ the 
data structure allocated through this macro call. FCS accesses 
the fields within the FDB relative to the address represented by 
this symbol. : 


The following examples are representative of FDBDF$ macro calls as 
they might appear in a source program: 


FDBOUT: FDBDFS$ ;ALLOCATES SPACE FOR AN FDB NAMED 
;"FDBOUT" AND ESTABLISHES THE 
7BEGINNING ADDRESS OF THE FDB. 


FDBIN: FDBDFS ;ALLOCATES SPACE FOR AN FDB NAMED 
7;"FDBIN" AND ESTABLISHES THE 
;BEGINNING ADDRESS OF THE FDB. 


As noted earlier, the source program must embody one FDBDFS$ macro call 
logically similar to ‘those above for each file to be accessed 
simultaneously by your program. FDBs can be reused for many different 
files, as long as the file currently using the FDB is closed before 
the next file is opened. The only requirement is that an FDB must be 
defined for every file to be opened simultaneously. 


2.2.1.2 FDATSA - Initialize File Attribute Section of FDB - The 
FDATSA macro call is used to initialize the file attribute section of 
the FDB when a new output file is to be created. If the file to be 
processed already exists, the first four parameters of the FDATSA 
initialization macro are not required, since FCS obtains the necessary 
information from the first 14 bytes of the user file attribute section 
of the specified file's header block (see Appendix F). This macro 
call has the following format: 


FDATSA rtyp,ratt,rsiz,cntg,aloc 

rtyp 
A symbolic value that defines the type of records to be built as 
the new file is created. One of three values must be specified, 


as follows: 


l. R.FIX - Indicates that fixed-length records are to be 
written in creating the file 


ratt 


rsiz 


cntg 


2. R.VAR - Indicates that variable-length records are to be 
written in creating the file 


3. R.SEQ - Indicates variable-length sequenced records are to 
be written in creating the file 


This parameter initializes FDB offset location F.RTYP. Since the 
symbols R.FIX, R.VAR, and R.SEQ initialize the same location in 
the FDB, these values are mutually exclusive. 


Symbolic values that may be specified to define the attributes of 
the records as the new file is created. The following symbolic 
values may be specified, as appropriate, to define the desired 
record attributes: 


e FD.FTN - Indicates that the first byte in each record will 
contain a FORTRAN carriage-control character 


e FD.CR - Indicates that the record is to be preceded by a 
<LF> character and followed by a <CR> character when the 
record is written to a carriage control device (for 
example, a line printer or a terminal) 


e FD.BLK - Indicates that records are not allowed to cross 
block boundaries 


e FD.PRN - Indicates that the record is preceded by a word 
containing carriage control information 


These parameters initialize the record attribute byte (offset 
location F.RATT) in the FDB. The values FD.FTN and FD.CR are 
mutually exclusive and must not be specified together. Apart 
from this restriction, the combination (logical OR) of multiple 
parameters specified in this field must be separated by an 
exclamation point (for example, FD.CR!FD.BLK). 


A numeric value that defines the size (in bytes) of fixed-length 
records to be written to the file. This value, which initializes 
FDB offset location F.RSIZ, need not be specified if R.VAR has 
been specified as the record type parameter above (for 
variable-length records). If R.VAR or R.SEQ is specified, FCS 
maintains a value in FDB offset location F.RSIZ that defines the 
size (in bytes) of the largest record currently written to the 
file. Thus, whenever an existing file containing variable-length 
records is opened, the value in F.RSIZ defines the size of the 
largest record within that file. By examining the value in this 
cell, a program can dynamically allocate record buffers for its 
open files. 


A signed numeric value that defines the number of blocks that are 
allocated for the file as it is created. The signed values have 
the following significance: 


e Positive Value - Indicates that the specified number of 


blocks is to be allocated contiguously at file-create time, 
and further that the file is to be contiguous 
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e Negative Value - Indicates that the two's complement of the 
specified number of blocks is to be allocated at 
file-create time, not necessarily contiguously, and further 
that the file is to be noncontiguous 


This parameter, which has 15 bits of magnitude (plus a sign bit), 
initializes FDB offset location F.CNTG. 


(You can specify an allocation of up to 24 bits by using the 
~-EXTND routine.) 


If you have a firm idea as to the desired length of the file, it 
is more efficient to allocate the required number of blocks at 
file-create time through this parameter, rather than requiring 
FCS to extend the file, if necessary, during the writing of the 
file (see aloc parameter below). 


Tf this parameter is not specified, then the file is created as 
an empty file; that is, no space is allocated within the file as 
it is created. 


Issuing the CLOSES$ macro call at the completion of 
file-processing resets the value in F.CNTG to 0. Thus, the usual 
procedure is to initialize this location at run time just before 
opening the file. Reinitialization is necessary if the FDB is 
reused. 


A signed numeric value that defines the number of blocks by which 
the file is extended, if FCS determines that file extension is 
necessary during the writing of the file. When the end of 
allocated space in the file is reached during writing, the signed 
value provided through this parameter causes file extension to 
occur, as follows: 


e Positive Value - Indicates that the specified number of 
blocks is to be allocated contiguously as additional space 
within the file, and further that the file is to be 
contiguous. 


NOTE 


Once a file has had blocks allocated, 
all future file extensions cause the 
file to become noncontiguous, even when 
aloc is a poSitive value. 


e Negative Value - Indicates that the two's complement of the 
specified number of blocks is to be allocated 
noncontiguously as additional space within the file, and 
further that the file is to be noncontiguous. 


This parameter, which also has 15 bits of magnitude (plus a sign 
bit), initializes FDB offset location F.ALOC. If this optional 
parameter is not specified, file extension occurs as follows: 


e If the number of virtual blocks yet to be written is 
greater than 1, the file is extended by the exact number of 
blocks required to complete the writing of the file. 
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e If only one additional block is required to complete the 
writing of the file, the file is extended in accordance 
with the volume's default extend value. 


The volume default extend size is established through the INITIALIZE, 
INITVOLUME, or MOUNT command, respectively. The volume default extend 
size cannot be established at the FCS level; this value must be 
established when the volume is initially mounted. 


The following statement is representative of an FDATSA macro call. 
This statement initializes the FDB in preparation for creating a new 
file containing fixed-length, 80-byte records that will be allowed to 
cross block boundaries. 


FDATSA R.FIX,,80. 


In the above example, the record attribute (ratt) parameter has been 
omitted, as indicated by the second comma (,) in the parameter string. 
Also, the cntg and aloc parameters have been omitted. Their omission, 
however, occurs following the last explicit specification, and their 
absence need not be indicated by trailing commas in the parameter 
String. Since the aloc parameter has been omitted, file extension (if 
it becomes necessary) is accomplished in accordance with the current 
default extend size in effect for the associated volume. 


If more than cne recerd attribute is specified in the ratt parameter 
field, such specifications must be separated by an exclamation point 
(!), as shown below: 


FDATSA R.VAR,FD.FTN! FD.BLK 


The above macro call enables a file of variable-length records to _ be 
created. Tne records will contain FORTRAN vyertical-formatting 
information for carriage control devices; the records will not be 
allowed to cross block boundaries. 


2.2.1.3 FDRCSA —- Initialize Record Access Section of FDB - The FDRCSA 
macro call is used to initialize the record access section of the FDB, 
and to indicate whether record or block I/O operations are to be used 
in processing the associated file. 


If record I/O operations (GETS and PUTS macro calls) are to be used, 
the FDRCSA or the FDRCSR macro call (see Section 2.2.2) establishes 
the FDB information necessary for record-oriented I/O. If block I/0 
operations (READS and WRITES macro calls) are to be used, however, the 
FDBKSA macro call (see Section 2.2.1.4) or the FDBKSR macro call (see 
Section 2.2.2) must also be specified in order to establish other 
values in the FDB required for block I/O. In this case, portions of 
the record access section of the FDB are physically overlaid with 
parameters from the FDBKSA/FDBKSR macro call. 


You must appropriately initialize the FDB to indicate whether’ record 
or block I/O operations are to be used in processing the associated 
file, prior to issuing the OPENS macro call to initialize file 
operations. 

The FDRCSA macro call takes the following format: 


FDRCSA racc,urba,urbs 


racc 


urba 
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Specifies which variation of block or record I/O is to be used to 
process the file. This parameter initializes the record access 
byte (offset location F.RACC) in the FDB. The first value below 
applies only for block I/0 (READS/WRITES) operations; all 
remaining values are specific to record I/O (GETS/PUTS) 
operations: 


e FD.RWM - Indicates that READS/WRITES (block I/O) operations 
are to be used in processing the file. If this value is 
not specified, GETS/PUTS (record I/O) operations are used 
by default. 


Specifying FD.RWM necessitates issuing an FDBKSA or an 
FDBKSR macro call in the program to initialize other 
offsets in the block access section of the FDB. Note also 
that the READS or WRITES macro call allows the complete 
specification of all the parameters required for block I/0 
operations. 


e FD.RAN - Indicates that random access mode is to be used in 
processing the file. If this value is not specified, 
sequential access mode is used by default. Refer to 


Section 1.5 for a description of random access mode. 


e FD.PLC - Indicates that locate mode is to be used in 
processing the file. If this value is not specified, move 
mode is used by default. 


e FD.INS - This value, which applies only for sequential 
files (and therefore cannot be specified jointly with the 
FD.RAN parameter above), indicates that a PUTS operation 
performed within the body of the file shall not truncate 
the file. 


Should you wish to perform a PUTS operation within the body 
of a file, the .POINT routine described in Section 4.10.1 
may be called. This routine, which permits a limited 
degree of random access to a file, positions the file to a 
user-specified byte within a virtual block in preparation 
for the PUTS operation. 


If FD.INS is not specified, a PUT$ operation within the 
file truncates the file at the point of insertion; that 
is, the PUTS operation moves the logical end-of-file (EOF) 
to a point just beyond the inserted record. However, no 
deallocation of blocks within the file occurs. 


Regardless of the setting of the FD.INS bit, a PUTS 
operation that is in fact beyond the current logical end of 
the file resets the logical end of the file to a point just 
beyond the inserted record. 


The symbolic address of a user record buffer to be used for GETS 
operations in move and locate modes, and for PUTS operations in 
locate mode. This parameter initializes FDB offset location 
F.URBD+2, and is specified only for record I/O operations. 


urbs 


A numeric value that defines the size (in bytes) of the user 
record buffer to be employed for GETS operations in move and 
locate modes, and for PUT$ operations in locate mode. This 
parameter initializes FDB offset location F.URBD, and is 
specified only for record I/O operations. 


You allocate and label a record buffer in a program by issuing a .BLKB 
or .BLKW directive. The address and the size of this area is then 
passed to FCS as the urba and the urbs parameters above. For example, 
a user record buffer may be defined through a statement that is 
logically equivalent to that shown below: 


RECBUF: .BLKB 82. 
RECBUF 


Is the address of the buffer and 82(decimal) is its size (in 
bytes). 


Beginning user record buffers on a word boundary can improve 
performance by allowing FCS to move the data with MOV instructions 
rather than MOVB instructions. 


Under certain conditions, you need not allocate a record buffer or 
specify the buffer descriptors (urba and urbs) for GETS or PUTS 
operations. These conditions are described in detail in Sections 
3.9.2 and 3.12.2, respectively. 


The following statement is representative of an FDRCSA macro call that 
is issued for a file that may be accessed in random mode: 


FDRCSA FD.RAN,BUFI1,160. 


The address of the user record buffer is specified through the symbol 
BUF1, and the size of the uSer record buffer (in bytes) is defined by 
the numeric value 160(decimal). 


If more than one value is specified in the record access (racc) field, 
an exclamation point (!) must separate the multiple values, as shown 
below: 


FDRCSA FD.RAN!FD.PLC,BUF1,160. 


In addition to the functions described for the first example, this 
example specifies that locate mode is to be used in processing the 
associated file. Note that the multiple parameters specified in the 
first field are separated by an exclamation point (!). 


2.2.1.4 FDBKSA - Initialize Block Access Section of FDB - The FDBKSA 
macro call is used to initialize the block access section of the FDB 
when block I/O operations (READS and WRITES macro calls) are to be 
used for file processing. Initializing the FDB with this macro call 
allows you to read or write virtual blocks of data within a file. 


Use of the FDBKSA macro call implies that the FDRCSA macro call has 
also been specified, since the FD.RWM parameter of the FDRCSA macro 
call does initial declaration of block I/O operations. Thus, for 
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block I/O operations, the FDRCSA macro call must be specified, as well 
as any one of the following macro calls, to appropriately initialize 
the block access section of the FDB: FDBKSA, FDBKSR, READS, or 
WRITES. 


Issuing the FDBKSA macro call causes certain portions of the record 
access section of the FDB to be overlaid with parameters necessary for 
block I/O operations. Thus, the terms "record access section" and 
"block access section" refer to a shared physical area of the FDB that 
is functional for either record or block I/O operations. 


The block I/O and record I/O FDB-initialization macros use the same 
area of the FDB for different data. Therefore, if record I/O 
operations are to be employed, neither the FDBKSA nor the FDBKSR macro 
call must be issued. 


The FDBKSA macro call is specified in the following format: 
FDBK$SA bkda,bkds,bkvb,bkef,bkst,bkdn 
bkda 


The symbolic address of an area in uSer memory space to be 
employed as a buffer for block I/O operations. This parameter 
initializes FDB offset location F.BKDS+2. 


bkds 


A numeric value that specifies the size (in bytes) of the block 
to be read or written when a block I/O request (READS or WRITES 
macro call) is issued. This parameter initializes FDB offset 
location F.BKDS. The size specified must be an even, positive 
(Sign bit must not be set) value; thus, the maximum number of 
bytes that can be specified is 32766. if an integral number of 
blocks are to be specified, the practical maximum number of bytes 
that can be specified is equal to 63 virtual blocks, or 
32256(decimal) bytes. 


bkvb 


A dummy parameter for compatibility with the FDBK$R macro call. 
The bkvb parameter is not specified in the FDBKSA macro call for 
the reasons stated in item 4 of Section 2.2.2.1. In short, 
assembly-time initialization of FDB offset locations F.BKVB+2 and 
F.BKVB with the virtual block number is meaningless, since any 
version of the generalized OPENSx macro call resets the virtual 
block number in these cells to 1 as the file is opened. 
Therefore, these cells can be initialized only at run time 
through either the FDBKSR macro call (see Section 2.2.2) or the 
I/O-initiating READS and WRITES macro calls (see Sections 3.15 
and 3.16, respectively). 


This dummy parameter should be reflected as a null specification 
(with a comma) in the parameter string only in the event that an 
explicit parameter follows. This null specification is required 
in order to maintain the proper position of any remaining 
field(s) in the parameter string. 


bkef 


A numeric value that specifies an event flag to be used during 
READS/WRITES operations to indicate the completion of a block I/0 
transfer. This parameter initializes FDB offset location F.BKEF; 
if not specified, event flag 32(decimal) is used by default. 


The function of an event flag is described in further detail in 
Section 2.8.1. 


bkst 


The symbolic address of a 2-word I/0 status block in your 
program. If specified, this optional parameter initializes FDB 
offset location F.BKST. 


The I/O status block, if it is to be used, must be defined and 
appropriately labeled at assembly time. Then, if the bkst 
parameter is specified, information is returned by the system _ to 
the I/O status block at the completion of the block I/O transfer. 
This information reflects the status of the requested operation. 
If this parameter is not specified, no information is returned to 
the I/O status block. 


NOTE 


If an error occurs during a READS or 
WRITES operation that would normally be 
reported aS a negative value in the 
first byte of the I/O status block, the 
error is not reported unless an I/O 
status block address is specified. 
Thus, you are advised to specify this 
parameter to allow the return of block 
I/O status information and to facilitate 
normal error reporting. 


The creation and function of the I/O status block are described 
in detail in Section 2.8.2. 


bkdn 


The symbolic address of an optional user-coded AST service 
routine. If present, this parameter causes’ the AST service 
routine to be initiated at the specified address upon completion 
of block I/0; if not specified, no AST trap occurs. This 
parameter initializes FDB offset location F.BKDN. 


ConSiderations relevant to the use of an AST service routine are 
presented in Section 2.8.3. 


The following example shows an FDBKSA macro call that utilizes all 
available parameter fields for initializing the block access section 
of the FDB: 

FDBKSA BKBUF,240.,,20.,ISTAT,ASTADR 
In this macro call, the symbol BKBUF identifies a block I/0 buffer 


reserved in the user program that will accommodate a 240(decimal)-—byte 
block. The virtual block number is null (for the reasons stated above 
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in the description of this parameter), and the event flag to be set 
upon block I/0 completion is 20(decimal). Finally, the symbol ISTAT 
specifies the address of the I/O status block, and the symbol ASTADR 
specifies the entry point address of the AST service routine. 


2.2.1.5 FDOPSA - Initialize File-Open Section of FDB - The FDOPSA 
macro call is used to initialize the file-open section of the FDB. In 
addition to a logical unit number, either a dataset descriptor pointer 
and/or a default filename block address is normally specified for each 
file that is to be opened. The latter two parameters provide FCS with 
the linkage necessary to retrieve file specifications from these 
user-created data structures in the program. 


Although both a dataset descriptor pointer (dspt) and the address of a 
default filename block (dfnb) may be specified for a given file, one 
or the other must be present in the FDB before that file can be 
opened. If, however, certain information is already present in the 
filename block as the result of prior program action, neither’ the 
dataset descriptor nor the default filename block is accessed by FCS, 
and. the file is opened through a process called “opening a file by 
file ID." This process, which is an efficient method of opening a 
file, is described in detail in Section 2.5. 


The dspt and dfnb parameters represent address values which point to 
user-defined data structures in the program. These data structures, 
which are described in detail in Section 2uAy provide file 
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The FDOPSA macro call takes the following form: 
FDOPSA lun,dspt,dfnb,facc,actl 
lun 


A numeric value that specifies a logical unit number. This 
parameter initializes FDB offset location F.LUN. All I/0 
operations performed in conjunction with this FDB are done 
through the specified logical unit number (LUN). Every active 
FDB must have a unique LUN. 


The logical unit number specified through this parameter may be 
any value from 1 through the largest value specified to the Task 
Builder through the UNITS option. This option specifies the 
number of logical units to be used by the task (see the Task 
Builder Reference Manual of the host operating system). 


dspt 


The symbolic address of a 6-word block in the user program 
containing the dataset descriptor. This user-defined data 
structure consists of a 2-word device descriptor, a 2-word 
directory descriptor, and a 2-word file name descriptor, as 
outlined in Section 2.4.1. 


The dspt parameter initializes FDB offset location F.DSPT. This 
address value, called the dataset descriptor pointer, is the 
linkage address through which FCS accesses the fields in the 
dataset descriptor. 


dfnb 


facc 


When the Command String Interpreter (CSI) is used to process 
command string input, a file specification is returned to the 
calling program in a format identical to that of the manually 
created dataset descriptor. The use of CSI as a dynamic command 
line processor is described in detail in Section 6.2. 


The symbolic address of the default filename block. This 
structure is allocated within the user program through the NMBLKS$ 
macro call (see Section 2.4.2). When specified, the dfnb 
parameter initializes FDB offset location F.DFNB, allowing FCS to 
access the fields of the default filename block in building the 
filename block in the FDB. 


Specifying the dfnb parameter in the FDOPSA (or the FDOPSR) macro 
call assumes that the NMBLKS macro call has been issued in the 
program. Furthermore, the symbol specified as the dfnb parameter 
in the FDOPSA (or the FDOPSR) macro call must correspond exactly 
to the symbol specified in the label field of the NMBLKS macro 
call. 


Any one, or any appropriate combination, of the following 
symbolic values indicating how the specified file is to be 
accessed: 


e FO.RD - Indicates that an existing file is to be opened for 
reading only. 


e FO.WRT - Indicates that a new file is to be created and 
opened for writing. 


e FO.APD - Indicates that an existing file is to be opened 
for append. 
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e FO.UPD - Indicates that an existing file is to be opened 
for update and, if necessary, extended. 


e FA.NSP - Indicates, in combination with FO.WRT above, that 
an old file having the same file specification is not to be 
superseded by the new file. Rather, an error code is to be 
returned if a file of the same file name, type, and version 
exists. 


e FA.TMP - Indicates, in combination with FO.WRT above, that 
the created file is to be a temporary file. 


e FA.SHR - Indicates that the file is to be opened for shared 
access. 


The facc parameter initializes FDB offset location F.FACC. 
The symbolic values FO.xxx, described above, represent the 
logical OR of bits in FDB location F.FACC. 


The information specified by this parameter can be 
overridden by an OPENS macro call, as described in Section 
3.7. It is overridden by an OPENSx macro call. 
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actl 


A symbolic value that is used to specify the following control 
information in FDB location F.ACTL: 


1. Magnetic tape position 


2. Whether a disk file that is opened for write is to be 
locked if it is not properly closed; for example, the 
task terminates abnormally 


3. Number of retrieval pointers to allocate for a disk file 
window 


4. Enable block locking 


Normallly, FCS supplies default values for F.ACTL. However, if 
FA.ENB is specified in combination with any of the symbolic 
values described below, FCS uses the information in F.ACTL. 
FAENB must be specified with the desired values to override the 
defaults. The following are the defaults for location F.ACTL: 


e For file creation, magnetic tapes are positioned to the end 
of the volume set. 


e At file open and close, tapes are not rewound. 


e A disk file that is opened for write is locked if it is not 
properly closed. 


e The volume default is used for the file window. 
The values listed below can be used in conjunction with FA.ENB: 


e FA.POS - Is meaningful only for output files and is 
specified to cause a magnetic tape to be positioned just 
after the most recently closed file for creating a new 
file, Any files that exist after that point are lost. If 
rewind is specified, it takes precedence over FA.POS, thus 
causing the tape to be positioned just after the VOL1 label 
for file creation. See Section 5.2.3. 


e FA.RWD - Is specified to cause a magnetic tape to be 
rewound when the file is opened or closed. 


Examples of using FA.ENB with FA.POS and. FA.RWD are 
provided in Section 5.2.8. 


e FA.DLK - Is specified to cause a disk file not to be locked 
if it is not properly closed. 


The number of retrieval pointers for a file window can be 
specified in the low-order byte of F.ACTL. The default 
number of retrieval pointers is the file-window mapping 
pointer count parameter (/WIN) included in the Initialize 
Volume or Mount Volume MCR commands; the default value for 
this parameter is 7. Retrieval pointers are used to point 
to contiguous blocks of the file on disk. Access’ to 
fragmented files may be optimized by increasing the number 
of retrieval pointers, that is, by increasing the size of 
the window. Similarly, since retrieval pointers use up 
pool space, additional memory can be freed by reducing the 
number of pointers for files with little or no 
fragmentation, for example, contiguous files. 
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e FA.LKL!FA.EXL - Is specified to lock all blocks that are 
accessed. See the RSX-11M/M-PLUS I/O Drivers Reference 
Manual for further information on block locking. 


As noted, if neither the dspt nor the dfnb parameter is specified, 
corresponding offset locations F.DSPT and F.DFNB contain 0. In this 
case, no file is currently associated with this FDB. Any attempt to 
open a file with this FDB results in an open failure. Either offset 
location F.DSPT or F.DFNB must be initialized with an appropriate 
address value before a file can be opened using this FDB. Normally, 
these cells are initialized at assembly time through the FDOPS$A macro 
call; but they may also be initialized at run time through the FDOPSR 
or the generalized OPENSx macro call (see Section 3.1). 


The following examples represent the FDOPSA macro call as it might 
appear in a source program: 


FDOPSA 1,,DFNB 

FDOPSA 2,OFDSPT 

FDOPSA 2,O0OFDSPT,DFNB 
FDOPSA 1,CSIBLK+C.DSDS 
FDOPSA 1,,DFNB,,FA.ENB!16. 


Note in the first example that the dataset descriptor pointer (dspt) 
is null, requiring that FCS rely on the run-time specification of the 
dataset descriptor pointer for the FDB or the use of the default 
filename block for required file information. 


In the second example, a dataset descriptor pointer (OFDSPT) has’ been 
specified, allowing FCS to access the fields in the dataset descriptor 
for required file information. 


The third example specifies both a dataset descriptor pointer and a 
default filename block address, causing FDB offset locations F.DSPT 
and F.DFNB, respectively, to be initialized with the appropriate 
values. In this case, FCS can access the dataset descriptor and/or 
the default filename block for required file information. By 
convention, FCS first seeks such information in the dataset 
descriptor; if all the required information is not present in this 
data structure, FCS attempts to obtain the missing information from 
the default filename block. 


The fourth example shows a macro call that takes as its second 
parameter a symbolic value that causes FDB offset location F.DSPT to 
be initialized with the address of the CSI dataset descriptor. This 
Structure is created in the CSI control block through invoking the 
CSI$ macro call. All considerations relevant to the use of CSI as a 
dynamic command line processor are presented in Section 6.2. 


The last example illustrates the use of the parameter actl to increase 
the number of retrieval pointers in the file window to 16. FA.ENB is 
specified to cause the contents of F.ACTL, rather than the defaults, 
to be used. 


In all the examples above, the value specified as the first parameter 
supplies the logical unit number to be used for all I/O operations 
involving the associated file. 
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2.2.1.6 FDBFSA - Initialize Block Buffer Section of FDB - The FDBFSA 


macro 


when 


cali is used to initialize the block buffer section of the FDB 
record I/O operations (GETS and PUTS macro calls) are to be used 


for file processing. Initializing the FDB with this macro call allows 
FCS to control the necessary blocking and debliocking of individual 
records within a virtual block as an integral function of processing 
the file. 


The FDBFSA macro call takes the following format: 


ovbs 


FDBFSA efn,ovbs,mbct,mbfg 


A numeric value that specifies the event flag to be used by FCS 
in synchronizing record I/O operations. This numeric value 
initializes FDB offset location F.EFN. This event flag is used 
internally by FCS; it must not be set, cleared, or tested by the 
user. 


If this parameter is not specified, event flag 32(decimal) is 
used by default. A null specification in this field is indicated 
by inserting a leading comma in the parameter string. 


A numeric value that specifies an FSR block buffer size, in 
bytes, which overrides the standard block size for the particular 
device associated with the file. This parameter initializes FDB 
offset location F.OVBS to the specified block’ buffer size. 


When ovbs is used in RSX-1l systems to specify an FSR_ block 
buffer size for disks, the desired number of bytes is specified 
in integral multiples of 512(decimal), overriding the standard 
512 (decimal) (one sector) block buffer size. Block buffer sizes 
up to 63 sectors (32256(decimal) bytes) can be specified for 
disks. Increasing the block buffer size in this manner greatly 
reduces average disk access time, since several contiguous 
sectors are generally read or written during a typical disk 
access operation. An override block size of 2048(decimal) bytes 
(4 sectors) or 2560(decimal) bytes (5 sectors) is recommended, 
since 2048(decimal) bytes also provides ANSI magtape buffer 
capability, and 2560(decimal) bytes is the Files-1ll default 
extend size. Note that once the file has been opened, FCS uses 
the ovbs field for other purposes. Thus, if the FDB is to be 
used for additional disk I/O operations, the ovbs parameter must 
be issued in an FDBFSR macro prior to accessing the disk. 


NOTE 
When block buffer sizes greater than 1 
sector (512 (decimal) bytes) are 


specified, $SFSR1 size must be increased 
accordingly. This is done by specifying 
an appropriate value for the bufsiz 
parameter in the FSRSZS$ macro call (see 
Section 2.6.1). 


In IAS systems, an override block size is allowed only for 
record-oriented devices (such as line printers) and sequential 
devices (such as magnetic tape units); if specified for a 
block-oriented device, the override block size is ignored. For 
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mbct 


mbfg 


spooled output to a record-oriented device, do not allocate a 
buffer less than a single sector (512(decimal) bytes). 


Routines that will read ANSI-standard magnetic tape without prior 
knowledge of the format of the files that will be read must 
specify an override block size of 2048(decimal) bytes. This 
value is sufficient for the largest ANSI-standard tape blocks. 


Issuing the CLOSE$ macro call (see Section 3.8) resets offset 
location F.OVBS in the associated FDB to 0. Therefore, this 
location should typically be initialized at run time, just before 
opening the file, particularly if an OPENS$x/CLOSE$ sequence for 
the file is performed more than once. 


On certain devices, such as line printers and terminals, the 
block size should not exceed the device's line width. The task 
can obtain the proper block size for these devices by issuing the 
Get LUN Information system directive for each device. (See the 
description for the Get LUN Information directive in the 
Executive Reference Manual for the operating system in use.) The 
Standard block size for each device is established at SYSGEN 
time, or by the MCR SET/BUF command. 


A numeric value that specifies the multiple buffer count, that 
is, the number of buffers to be used by FCS in processing the 
associated file. This parameter initializes FDB offset location 
F.MBCT. If this value is greater than 1, multiple buffering is 
effectively declared for file processing. In this case, FCS 
employs either read-ahead or write-behind operations, depending 
on which of two symbolic values is specified as the mbfg 
Parameter (see below). 


If the mbct parameter is specified as null or 0, FCS uses the 
default buffer count contained in symbolic location .MBFCT in 
SSFSR2 (the program section in the FSR containing impure data). 
This cell normaliy contains a default buffer count of i. If 
desired, this value can be modified, as noted in the discussion 
following the mbfg parameter below. 


If, in specifying the FSRSZ$ macro call (see Section 2.6.1), 
sufficient memory space has not been allocated to accommodate the 
number of buffers established by the mbct parameter, FCS 
allocates as many buffers as can fit in the available space. 
Insufficient space for at least one buffer causes FCS to return 
an error code to FDB offset location F.ERR. 


The user can initialize the buffer count in F.MBCT through either 
the FDBFSA or the FDBFSR macro call. The buffer count so 
established is not altered by FCS and, once set, need not be of 
further concern to the user. 


When input is from record devices (for example, a card reader), 
F.MBCT should not be greater than 2. 


A symbolic value that specifies the type of multiple buffering to 
be employed in processing the file. Either of two values may be 
specified to initialize FDB offset location F.MBFG: 


e FD.RAH - Indicates that read-ahead operations are _ to be 
used in processing the file 
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e FD.WBH - Indicates that write-behind operations are to beé 
used in processing the file 


These parameters are mutually exclusive; that is, one or _ the 
other, but not both, may be specified. 


Specifying this parameter assumes’ that the buffer count 
established in the mbct parameter above is greater than l. If 
multiple buffering has thus been declared, omitting the mbfg 
parameter causes FCS to use read-ahead operations by default for 
all files opened using the OPENSR macro call; Similarly, 
write-behind operations are used by default for all files opened 
using other forms of the OPENSx macro call. 


If these default buffering conventions are not desired, you can 
alter the value in the F.MBFG dynamically at run time. This is 
done by issuing the FDBFSR macro call, which takes as the mbfg 
parameter the appropriate control flag (FD.RAH or FD.WBH). This 
action must be taken, however, before opening the file. 


Offset location F.MBFG in the FDB is reset to 0 each time the 
associated file is closed. 


NOTE 


When using write-behind multi- 
buffering, there is no gain in 
efficiency if the size of the file 
must be increased in order to make 
room for the data to be written. 
If a file is being written at the 
end, using default extension, there 
will be one extend operation for 


each five write operations; thus, 
only 803% of the write-behind 
operations will actually be 


overlapped with processing. This 
percentage can be _ increased as 
follows: 


1. Space for the file can be completely 
preallocated, either by using the "cntg" 
Parameter in the FDOPS$x macro, or by 
using the .EXTND subroutine. 


2. The default extension amount can be 
increased from five blocks by using the 
"aloc" parameter of the FDATSx macro 
call. For example, if an "“aloc" 
parameter of 10(decimal) is specified, 
the number of write-behind operations 
that will be overlapped will increase to 
90%. 


3. The file can be accessed using random 
I/O. Since issuing PUTSR macros’ to 
access random preexisting locations in 
the file does not require extends, the 
percentage of overlapped operations is 
increased. 
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You can change the default buffer count, if desired, by modifying a 
location in $S$FSR2, the second of two program sections comprising the 
FSR. A location defined as .MBFCT in S$$FSR2 normally contains a 
default buffer count of 1. This default value may be changed, as 
follows: 


1. Apply a global patch to .MBFCT at task-build time to specify 
the desired number of buffers. 


2. For MACRO-11l programs, use the EXTSCT Task Builder directive 
(see Section 2.7.1) to allocate more space for the FSR block 
buffers; for FORTRAN programs, use the ACTFIL Task Builder 
directive (see Section 2.7.2) to allocate more space for the 
FSR block buffers. 


Because the above procedure alters the default buffer count for all 
files to be processed by your program, it may be desirable to force 
Single buffering for any specific file(s) that would not benefit from 
multiple buffering. In such a case, you can set the buffer count in 
F.MBCT for a specific file to 1 by issuing the following macro call 
for the applicable FDB: 


FDBFSA_ ,,1 


The value 1 specifies the buffer count (mbct) for the desired file and 
is entered into offset location F.MBCT in the applicable FDB. Note in 
the example above that the event flag (efn) and the override block 
buffer size (ovbs) parameters are null; these null values are used 
for illustrative purposes only and should not be interpreted as 
conditional specifications for establishing single-buffered 
operations. 


The following examples are representative of the FDBFSA macro call as 
it might appear in a program: 


FDBF$A 25.,,1 
FDBFSA 25.,,2,FD.RAH 
FDBFSA ,,2,FD.WBH 


The first example specifies that event flag 25(decimal) is to be used 
in synchronizing record I/O operations and that single buffering is to 
be used in processing the file. 


The second example also specifies event flag 25 (decimal) for 
synchronizing record I/O operations, and in addition establishes 2 as 
the multiple buffer count. The buffers so specified are to be used 
for read-ahead operations, as indicated by the final parameter. 


The last example allows event flag 32(decimal) to be used by default 
for synchronizing record I/O operations, and the two buffers specified 
in this case are to be used for write-behind operations. 


Note in all three examples that the second parameter, that is, the 
override block size parameter (ovbs), is null; thus, the standard 
block size in effect for the device in question will be used for all 
file I/O operations. 
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2.2.2 Run-Time FDB Initialization Macros 


Although the FDB is allocated and can be initialized during program 
assembly, the contents of specific sections of the FDB can also be 
initialized or changed at run time by issuing any of the following 
macro calls: 


e FDATSR - Initializes or alters the file attribute section 
of the FDB. 


e FDRCSR - Initializes or alters the record access section of 
the FDB. 
e FDBKSR - Initializes or alters the block access section of 


the FDB (see item 4 below). 


e FDOPSR - Initializes or alters the file-open section of the 
FDB. 

e FDBFSR - Initializes or alters the block buffer section of 
the FDB. 


‘There are no default values for run-time FDB macros (except for the 
FDB address). At run time, the values currently in the FDB are used 
unless they are explicitly overridden. For example, values stored in 
the FDB at assembly time are used at run time unless they are 
overridden. 


2.2.2.1 Run-Time FDB Macro-Call Exceptions - The format and the 
parameters of the run-time FDB initialization macros are identical to 
the assembly-time macros described earlier, except as noted below: 


e An R rather than an A must appear as Ene last character in the 
run-time symbolic macro name. 


e The first parameter in all run-time macro calls must be _ the 
address of the FDB associated with the file to be processed. 
All other parameters in the run-time macro calls are identical 
to those described in Sections 2.2.1.2 through 2.2.1.6 for the 
assembly-time macro calls, except as noted in items 3 and 4 
below. 


e The parameters in the run-time macro calls must be valid 
MACRO-11 source operand expressions. These parameters may be 
address values or literal values; they may also represent the 
contents of registers or memory locations. In short, any 
value that is a valid source operand in a MOV or MOVB 
instruction may be specified in a run-time macro call. In 
this regard, the following conventions apply: 


- If the parameter is an address value or a literal value 
that is to be placed in the FDB; that is, if the 
Parameter itself is to be taken as an argument, it must 
be preceded by the number sign (#). This symbol is the 
immediate expression indicator for MACRO-1l programs, 
cauSing the associated argument to be taken literally in 
initializing the appropriate cell in the FDB. Such 
literal values may be specified as follows: 


FDOPSR #FDBADR, $1, #DSPT, #DFNB 


1. 


- If the parameter is the address of a location containing 
an argument that is to be placed in the FDB, the 
parameter must be preceded by the number sign (#). Such 
a parameter may be specified as follows: 


ONE: - WORD 1 


FDOPSR #FDBADR, ONE, #DSPT, #DFNB 


where ONE represents the symbolic address of a location 
containing the desired initializing value. 


- But, if the parameter is a register specifier (for 
example, R4), the parameter must not be preceded by the 
number sign (#). Register specifiers are defined 
MACRO-11 symbols and are valid expressions in any 
context. 


NOTE 


RO can only be specified in the first parameter 
(FDB address). Any other use of RO will fail. 
(See Section 2.2.2.2, items 1 and 2.) 


Thus, in contrast, parameters specified in assembly-time macro 
calls are used as arguments in generating data in .WORD or 
-BYTE directives, while parameters specified in run-time macro 
calls are used aS arguments in MOV and MOVB machine 
instructions. 


As noted in the description of the FDBKSA macro call in 
Section 2.2.1.4, assembly-time initialization of the FDB with 
the virtual block number is meaningless, since issuing the 
COPENSx macra call to prepare a fiie for processing 
automatically resets the virtual block number in the FDB to l. 
For this reason, the virtual block number can be specified 
only at run time after the file has been opened. This may be 
accomplished by issuing either the FDBKSR macro call or the 
I/O-initiating READS/WRITES macro call. In all three cases, 
the relevant field for defining the virtual block number is 
the bkvb parameter. The READS and WRITES macro calls are 
described in detail in Sections 3.15 and 3.16, respectively. 


At assembly time, you must reserve and label a 2-word block in 
the program that is to be used for temporarily storing the 
virtual-block number appropriate for intended block I/O 
operations. Since you are free to manipulate the contents of 
these two locations at will, any virtual block number 
consistent with intended block I/O operations may be defined. 
By specifying the symbolic address (that is, the label) of 
this field as the bkvb parameter in the selected run-time 
macro call, you can make the virtual block number available to 
FCS. 


In preparing for block I/O operations, you must perform the 
following general procedures: 


At assembly time, reserve a 2-word block in your’ program 
through a statement that is logically equivalent to the 
following: 
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VBNADR: .BLKW 2 


The label VBNADR names this 2-word block and defines its 
address. This symbol is used subsequently as_ the bkvb 


parameter in the selected run-time macro cail for 
initializing the FDB. 


At run time, load this field with the desired virtual block 
number. This operation may be accomplished through 
statements logically equivalent to those shown below: 


CLR VBNADR 
MOV #10400, VBNADR+2 


Note that the first word of the block is cleared. The MOV 
instruction then loads the second (low-order) word of the 
block with a numeric value. This value constitutes the 16 
least significant bits of the virtual block number. 


If the desired virtual block number cannot be completely 
expressed within 16 bits, the remaining portion of the 
virtual block number must be stored in the first (high-order) 
word of the block. This may be accomplished through 
statements logically equivalent to the following: 


MOV #1,VBNADR 
MOV #10400, VBNADR+2 


As a result of these two instructions, 31 bits of value are 
defined in this 2-word block. The first word contains the 15 
most Significant bits of the virtual block number, and_ the 
second word contains the 16 least significant bits. Thus, 
the virtual block number is an unsigned value having 31 bits 
of magnitude. You must ensure that the sign bit in the 
high-order word is not set. 


Open the desired file for processing by issuing the 
appropriate version of the generalized OPEN$x macro call (see 
Section 3.1). 


Issue either the FDBKSR macro call or the READS/WRITES macro 
call, as appropriate, to initialize the relevant FDB with the 
desired virtual block number. 


If the FDBKSR macro call is elected, the following is a 
representative example: 


FDBKSR #FDBIN,,,#VBNADR 


Regardless of the particular macro call used to supply the 
virtual block number, the two words at VBNADR are loaded into 
F.BKVB and F.BKVB+2. The first of these words (F.BKVB) is 0 
if 16 bits are sufficient to express the desired virtual 
block number. The I/O-initiating READS/WRITES$ macro call may 
then be issued. 


Should you choose, however, to initialize the FDB directly 
through either the READS or WRITES macro call, the virtual 
block number may be made available to FCS through a statement 
such as that shown below: 


READS #FDBIN, #INBUF, #BUFSIZ,#VBNADR 
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The symbol VBNADR represents the address of the 2-word block 
in your program containing the virtual block number. 


2.2.2.2 Specifying the FDB Address in Run-Time Macro Calls - In 
relation to item 2 of the exceptions noted above, the address of the 
FDB associated with the file to be processed corresponds to the 
address value of the user-defined symbol appearing in the label field 
of the FDBDF$ macro call (see Section 2.2.1.1). For example, the 
statement 


FDBOUT: FDBDFS$ 


in addition to allocating space for an FDB at assembly time, binds the 
label FDBOUT to the beginning address of the FDB associated with this 
file. The address value so established can then be specified as_ the 
initial parameter in a run-time macro call in any one of three ways: 


1. The address of the appropriate FDB may be specified as an 
explicit parameter in a run-time macro call, as indicated in 
the following statement: 


FDATSR #FDBOUT,#R.VAR,#FD.CR 


The argument FDBOUT is taken literally by FCS as the address 


of an PDB; furthermore, this address value, by convention, 
is stored in general register zero (RO). Whenever this 
method of specifying the FDB address is employed, the 
previous contents of RO are overwritten (and thus destroyed). 
Therefore, you must exercise care in issuing subsequent 
run-time macro calls to ensure that the present value of RO 
is suitable to current purposes. 


2. A general register specifier may be used as the _ initial 
parameter in a run-time macro call. When a register other 
than RO is used, the contents of the specified register are 
moved to RO. The previous contents of RO are overwritten 
(and thus destroyed). 


The following statement reflects the use of a general 
register to specify the FDB address: 


FDATSR RO,#R.VAR,#FD.CR 


In this case, the current contents of RO are taken by FCS as 
the address of the appropriate FDB. This method assumes that 
the address of the FDB has been previously loaded into RO 
through some overt action. Note, when using this method to 
specify the FDB address, that the immediate expression 
indicator (#) must not precede the register specifier (RO). 


3. A null specification may be used as the initial parameter in 
a run-time macro call, as shown below: 


FDATSR- ,#R.VAR,#FD.CR 


In this case, the current contents of RO are taken by default 
as the address of the associated FDB. As in method 2 above, 
RO is assumed to contain the address of the desired FDB. 
Although the comma in this instance constitutes a valid 
specification, you are advised to employ methods 1 and 2 for 
consistency and clarity of purpose. 
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These three methods of specifying the FDB address also apply to all 
the FCS file-processing macro calls described in Chapter 3. 


2.3 GLOBAL VERSUS LOCAL DEFINITIONS FOR FDB OFFSETS 


Although the FDB offsets can be defined either locally or globally, 
the design of FCS does not require that you be concerned with the 
definition of FDB offsets locally. To some extent, this design 
consideration is based on the manner in which MACRO-il1 handles 
symbols. 


Whenever a symbol appears in the source program, MACRO-11 
automatically assumes that it is a global symbol unless it is 
presently defined within the current assembly. Such a symbol must be 
defined further on in the program; otherwise, it will be treated by 
MACRO-11 as.a default global reference, requiring that it be resolved 
by the Task Builder. 


Thus, the question of global versus local symbols may simply be a 
matter of the programmer's not defining the FDB offsets and bit values 
localiy in coding the program. Such undefined symbols thus’ become 
global references, which are reduced to absolute definitions at 
task-build time. 


It should be noted that global symbols may be used as operands and/or 
macro-call parameters anywhere in the source program coding, as 
described in the following section. 


2.3.1 Specifying Global Symbols in the Source Coding 


Throughout the descriptions of the assembly-time macros (see Sections 
2.2.1.2 through 2.2.1.6), global symbols are specified as parameters 
in the macro calls. As noted earlier, such symbols are treated by 
MACRO-11 as default global references. 


For example, the global symbol FD.RAN may be specified as the initial 
parameter in the FDRCSA macro call (see Section 2.2.1.3). At 
task-build time, this parameter is reduced to an absolute symbol 
definition, causing a prescribed bit to be set in the record access 
byte (offset location F.RACC) of the FDB. 


Global symbols may also be used as operands in user program 
instructions to accomplish operations associated with FDB offset 
locations. For example, global offsets such as F.RACC, F.RSIZ, and 
F.RTYP may be specified as operands in the source coding. Assume, for 
example, that an FDBDFS macro call (see Section 2.2.1.1) has been 
issued in the source program to allocate space for an FDB, as follows: 


FDBIN: FDBDFS$ 


The coding sequence shown below may then appear in the source program, 
illustrating the use of the global offset F.RACC: 


MOV #FDBIN, RO 
MOVB #FD.RAN,F.RACC (RO) 


Note that the beginning address of the FDB is first moved into general 
register zero (RO). However, if the desired value already exists in 
RO as the result of previous action in the program, you need issue 
only the second MOV instruction (which appropriately references RO). 
As a consequence of this instruction, the value FD.RAN initializes FDB 
offset location F.RACC. 


An equivalent instruction is the following: 
MOVB #FD.RAN, FDBIN+F.RACC 


which similarly initializes offset location F.RACC in the FDB with the 
value of FD.RAN. Global symbols may be used anywhere in the program 
in this manner to effect the dynamic storage of values within the FDB. 


2.3.2 Defining FDB Offsets and Bit Values Locally 


If you wish to declare explicitly that all FDB offsets and bit values 
are to be defined locally, you can do so by invoking two macro calls 
in the source program. The first of these, FDOFSL, causes the offsets 
for FDBs to be defined within your program. Similarly, bit values for 
all FDB parameters may be defined locally by invoking the FCSBT$ macro 
call. You can invoke these macro calls anywhere in your program. 


When issued, the FDOFSL and FCSBTS macro calls define symbols in a 
manner roughly equivalent to: 

F.RTYP = xxxx 

F.RACC = xxxx 

F.RSIZ = xxxx 


where xxXxx represents the value assigned to the corresponding symbol. 


In other words, the macros for defining FDB offsets and bit values 
locally do not generate any code. Their function is simply to create 
absolute symbol definitions within the program at assembly time. The 
symbols so defined, however, appear in the MACRO-11 symbol table, 
rather than in the source program listing. Such local symbol 
definitions are thereby made available to MACRO-11 during assembly, 


rather than forcing them to be resolved by the Task Builder. 


Whether the FDOFSL and FCSBTS macro calls are invoked should not in 
any way affect the coding style or the manner in which the FDB offsets 
and bit values are used. 


Note, however, if the FDOFSL macro call is issued, the NBOFSL macro 
call for the local definition of the filename block need not be issued 
(see Section 2.4.2). The FDOFSL macro call automatically defines all 
FDB offsets locally, including those for the filename block. 


If any of the above named macro calls is to be issued in your program, 
it must first be listed as an argument in an .MCALL directive (see 
Section 2.1). 


2.4 CREATING FILE SPECIFICATIONS WITHIN THE USER PROGRAM 


Certain information describing the file must be present in the FDB 
before the file can be opened. The file is located using a file 
specification that contains the following: 
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1. A device name and unit number. 


2. A directory string consisting of a group number and a member 
number that specify the User File Directory (UFD) to be used 
for the file. The term "UFD" is synonymous with the term 
"file directory string” appearing throughout this manual. 


3. A file name. 
4. A file type (RSX-11) or file extension (IAS). 
5. A file version number. 


The term "file specifier" is sometimes used as a synonym for "file 
specification." 


A file specification describing the file to be processed is 
communicated to FCS through two user-created data structures: 


1. The dataset descriptor. This tabular structure may be 
created and initialized manually through the use of .WORD 
directives. Section 2.4.1 describes this data structure in 
detail. 


2. The default filename block. In contrast to the manually 
created dataset descriptor, the default filename block is 
created by issuing the NMBLKS macro call. This macro call 
allocates a block of storage in your program at assembly time 
and initializes this structure with parameters supplied in 
the call. This structure is described in detail in Section 
204% 2s 


As noted in Section 2.2.1.5, the FDOPSA or the FDOPSR macro call is 
issued to initialize the FDB with the addresses of these data 
structures. These address values are supplied to FCS through the dspt 
and dfnb parameters of the selected macro call. FCS uses these 
addresses to access the fields of the dataset descriptor and/or’ the 
default filename block for the file specification required in opening 
a specified file. 


By convention, a required file specification is first sought by FCS in 
the dataset descriptor. Any nonnull data contained therein is 
translated from ASCII to Radix-50 form and stored in the appropriate 
offsets of the filename block. This area of the FDB then serves as 
the execution time repository for the information describing the file 
to be opened and processed. If the dataset descriptor does not 
contain the required information, FCS attempts to obtain the missing 
information from the default filename block. If neither of these 
structures contains the required information, an open failure occurs. 


Note, however, that the device name and the unit number need not be 
specified in either the dataset descriptor or the default filename 
block, since these values are defaulted to the device and unit 
assigned to the LUN at task-build time if not explicitly specified. 


The FCS file-processing macro calls used in opening files are 
described in Chapter 3, beginning with the generalized OPENSx macro 
call in Section 3.1. 


For a detailed description of the format and content of the filename 
block, the reader should refer to Appendix B. 
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2.4.1 Dataset Descriptor 


The dataset descriptor is often oriented toward the use of .a_ fixed 
(built-in) file name in your program. A given application program, 
for example, may require access only to a limited and nonvariable 
number of files throughout its execution. By defining the names of 
these files at assembly time through the dataset descriptor mechanism, 
such a program, once initiated, executes to completion without 
requiring additional file specifications. 


This structure, a 6-word block of storage that you can create manually 
within your program by using .WORD directives, contains information 
describing a file that you intend to open during the course of program 
execution. In creating this structure, you can define any one or all 
of three possible string descriptors for a particular file, as 
follows: 


l. A 2-word descriptor for an ASCII device name string 
2. A 2-word descriptor for an ASCII file directory string 
3. A 2-word descriptor for an ASCII file name string 


This data structure is allocated in your program in the following 
format: 


DEVICE-NAME STRING DESCRIPTOR 
Word 1 - Contains the length (in bytes) of the ASCII device 
name string. 
This string consists of a 2-character alphabetic 
device name, followed by an optional octal unit 
number and an optional coion. You can create 
these strings by issuing statements such as those 
below: 
DEVNM: .ASCIIT /DKO:/ 
DEVNM: .ASCII /TT10:/ 
Word 2 - Contains the address of the ASCII device name 


string. 
DIRECTORY STRING DESCRIPTOR 


Word 3 - Contains the length (in bytes) of the ASCII file 
directory string. 


This string consists of a group number and a 
member number, separated by a comma (,). The 
entire string is enclosed in brackets. For 
example, [200,200] is a directory string. You can 
create a directory string by issuing statements 
such as those that follow: 


DIRNM: .ASCII /[200,200]/ 

DIRNM: .ASCII /[40,100]/ 
If you wish to specify an explicit file directory 
different from the UIC under which you are 


currently running, the dataset descriptor 
mechanism permits that flexibility. 
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Word 4 - Contains the address of the ASCII file directory 
String. 


FILENAME STRING DESCRIPTOR 


Word 5 - Contains the length (in bytes) of the ASCII file 
name string. 


This string consists of a file name up to 9 
characters in length, an optional 3-character file 
type designator, and an optional file version 
number. The file name and file type must be 
separated by a dot (.), and the file version 
number must be preceded by a semicolon. A file 
name string may be created as shown below: 


FILNM: .ASCII /PROG1].OBJ;7/ 


For Files-ll, only the characters A through Z and 
0 through 9 may be used in composing an ASCII file 
name string. 

An ANSI magnetic tape file name string may 
contain, in addition to the above, the following 
special characters: 


SP! "%$& ' () *®*+,-.2. /3: 7 € =D? 


A name that contains any of these characters must 
be enclosed in quotation marks. If a quotation 
mark is part of the name, the string must’ contain 
two quotation marks. An ANSI file name string may 
be created as shown below: 


FILNM: .ASCII /"PROG""2""3%&,"37/ 
The file name created in the above example is: 


PROG"2"3%&; 37 


NOTE 


Semicolon is a legal character in the 
name string. To delimit a version 
number, the semicolon must be outside 
the quoted string. 


Word 6 - Contains the address of the ASCII file name 
string. 


A length specification of 0 in Word 1, 3, or 5 of the dataset 
descriptor indicates that the corresponding device name, directory, or 
file name string is not present in your program. For example, the 
coding below creates a dataset descriptor containing only a 2-word 
ASCII file name string descriptor: 


FDBOUT: FDBDFS$ ;CREATES FDB. 
FDATSA R.VAR,FD.CR ;INITIALIZES FILE-ATTRIBUTE SECTION. 
FDRCSA_ ,RECBUF,80. ; INITIALIZES RECORD-ACCESS SECTION. 
FDOPSA OUTLUN,OFDSPT ;INITIALIZES FILE-OPEN SECTION. 
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OFDSPT: .WORD 0,0 ;NULL DEVICE-NAME DESCRIPTOR. 
- WORD 0,0 ;NULL DIRECTORY DESCRIPTOR. 
- WORD ONAMSZ , ONAM ;FILENAME DESCRIPTOR. 


ONAM : eASCII /OUTPUT.DAT/ ;DEFINES FILENAME STRING. 
ONAMSZ=.—-ONAM ;DEFINES LENGTH OF FILENAME STRING. 


Note first that an FDB labeled FDBOUT is created. Observe further 
that the FDOPSA macro call takes as its second parameter the symbol 
OFDSPT. This symbol represents the address value stored in FDB offset 
location F.DSPT. This value enables the .PARSE routine (see Section 
4.7.1) to access the fields of the dataset descriptor in building the 
filename block. 


The symbol OFDSPT also appears in the label field of the first .WORD 
directive, defining the address of the dataset descriptor for the 
-PARSE routine. The .WORD directives each allocate two words of 
Storage for the device name descriptor, the file directory descriptor, 
and the file name descriptor, respectively. 

In the example above, however, note that the first two descriptor 
fields are filled with zeros, indicating null specifications. The 
last .WORD directive allocates two words that contain the size and the 
address of the file name string, respectively. The file name string 
itself is explicitly defined in the .ASCII directive that follows. 


Note that the statements defining the file name string need not be 
physically contiguous with the dataset descriptor. For each such 
ASCII string referenced in the dataset descriptor, however, 


corresponding statements must appear elsewhere in the source program 


to define the appropriate ASCII data string(s). 


A dataset descriptor for each of several files to be accessed by your 
program may be defined in this manner. 


2.4.2 Default Filename Block - NMBLKS Macro Call 


As noted earlier, you may also define a default filename block in the 
program as a means of providing required file information to FCS. For 
this purpose, you can issue the NMBLK$ macro call in connection with 
each FDB for which a default filename block is to be defined. When 
this macro call is issued, space is allocated within your program for 
the default filename block, and the appropriate locations within this 
data structure are initialized according to the parameters supplied in 
the call. 


Note in the parameter descriptions below that symbols of the form 
N.xxxx are used to represent the offset locations within the filename 
block. These symbols are differentiated from those that apply to the 
other sections of the FDB by the beginning character N. All versions 
of the generalized OPENSx macro call (see Section 3.1) use these 
symbols to identify offsets in storing file information in the 
filename block. 
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The NMBLKS$ macro call is specified in the following format: 
label: NMBLKS fnam,ftyp,fver,dvnm,unit 
label 


A user-defined symbol that names the default filename block and 
defines its address. This label is the symbolic value normally 
specified as the dfnb parameter when the FDOPSA or the FDOPSR 
macro call is issued. This causes FDB offset location F.DFNB to 
be initialized with the address of the default filename block. 


The default file name. This parameter may consist of up to nine 
ASCII characters. The character string is stored as six bytes in 
Radix-50 format, starting at offset location N.FNAM of the 
default filename block. 


ftyp 


The default file type. This parameter may consist of up to three 
ASCII characters. The character string is stored as two bytes in 
Radix-50 format in offset location N.FTYP of the default filename 
block. 


fver 


The default file version number (binary). When specified, this 
binary value identifies a particular version of a file. This 
value is stored in offset location N.FVER of the default filename 
block. 


dvnm 


The default name of the device upon which the volume containing 
the desired file is mounted. This parameter consists of two 
ASCII characters that are stored in offset location N.DVNM of the 
default filename block. 


unit 


A binary value identifying which unit (among several like units) 
is to be used in processing the file. If specified, this numeric 
value is stored in offset location N.UNIT of the default filename 
block. 


Only the characters A through Z and 0 through 9 may be used in 
composing the file name and file type strings discussed above. 
Although the file version number and the unit number discussed above 
are binary values, these numbers are normally represented in octal 
form when printed, when input by a command string, or when supplied 
through a dataset descriptor string. 


As evident from the foregoing, all the default information supplied in 
the NMBLKS$ macro call is stored in the default filename block at 
offset locations that correspond to identical fields in the filename 
block within the FDB. This default information is moved into the 
corresponding offsets of the filename block when any version of the 
generalized OPENS$x macro call is issued under any of the following 
conditions: 


e All the file information required by FCS to open the file is 
not present in the dataset descriptor. Missing information is 
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then sought in the default filename block by the  .PARSE 
routine (see Section 4.7.1), which is automatically invoked as 
a result of issuing any version of the generalized OPENSx 
Macro call. 


e A dataset descriptor has not been created in your program. 


e A dataset descriptor is present in your program, but the 
address of this structure has not been made available to FCS 
through any of the assembly-time or run-time macro calls’ that 
initialize FDB offset location F.DSPT. 


The following coding illustrates the general method of specifying the 
NMBLK$ macro call: 


FDBOUT: FDBDF$ ;ALLOCATES SPACE FOR AN FDB. 
FDATSA R.VAR,FD.CR ;INITIALIZES FILE-ATTRIBUTE SECTION. 
FDRCSA_ ,RECBUF,80. INITIALIZES RECORD-ACCESS SECTION. 
FDOPSA OUTLUN, ,OFNAM ; INITIALIZES FILE-OPEN SECTION. 

FDBIN: FDBDFS$ ;ALLOCATES SPACE FOR AN FDB. 
FDRCSA_ ~,RECBUF,80. ; INITIALIZES RECORD-ATTRIBUTE SECTION. 
FDOPSA INLUN,,IFNAM ;INITIALIZES FILE-OPEN SECTION. 

OFNAM: NMBLKS OUTPUT,DAT ;ESTABLISHES FILENAME AND FILE TYPE. 


IFNAM: NMBLKS INPUT,DAT,,DT,1 ;ESTABLISHES FILENAME, FILE TYPE, 
ee LC ah eta. act Oe neue aes 

The first NMBLKS macro call in the coding sequence above creates a 
default filename block to establish default information for the FDB, 
named FDBOUT. The label OFNAM in this macro defines the beginning 
address of the default filename block allocated within your program. 
Note that this symbol is specified as the dfnb parameter in the FDOPSA 
macro call associated with this default filename block to initialize 
the file open section of the corresponding FDB. The accompanying 
Parameters in the first NMBLKS macro call define the file name and the 
file type, respectively, of the file to be opened; all remaining 
parameter fields in this call are null. 


The second NMBLKS macro call accomplishes essentially the same 
operations in connection with the FDB, named FDBIN. Note in this 
macro call that the third parameter (the file version number) is null, 
as reflected by the extra comma. This null specification indicates 
that the latest version of the file is desired. All other parameter 
fields contain explicit declarations defining default information for 
the applicable FDB. 


You can define the offsets for a filename block locally in your 
program, if desired, by issuing the following macro call: 


NBOFSL 


This macro call does not generate any code. Its function is merely to 
define the filename block offsets locally, presumably to conserve 
symbol table space at task-build time. The NBOFSL macro call need not 
be issued if the FDOFSL macro call has’ been invoked, since the 
filename block offsets are defined locally as an automatic result of 
issuing the FDOFSL macro call. 


If desired, you may initialize fields in the default filename block 
directly with appropriate values. This may be accomplished with 
in-line statements in the program. For example, a specific offset in 
the default filename block may be initialized through coding that is 
logically equivalent to the following: 
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DFNB: NMBLKS RSXLIB,OBJ 


NUTYP: .RAD50 /DAT/ 


MOV NUTYP,DFNB+N.FTYP 


where the symbol NUTYP in the MOV instruction represents the address 
of the newly defined Radix-50 file type DAT, which is to be moved into 
destination offset N.FTYP of the default filename block labeled DFNB. 
You can manually initialize any of the offsets within the default 
filename block in this manner to establish desired values or _ to 
override previously initialized values. 


NOTE 


The NMBLKS$ macro cannot be used _ to 
create a file name containing 
non-Radix-50 characters or a file name 
that is not in the normal FILNAME.TYP 
format. A program that uses the file 
name format permitted for ANSI magnetic 
tape must set up the file name in a 
dataset descriptor. 


2.4.3 Dynamic Processing of File Specifications 


If you wish to make use of routines available from the system object 
library ({1,1]SYSLIB.OLB) for processing command line input 
dynamically, you should consult Chapter 6. Chapter 6 describes’ the 
Get Command Line (GCML) routine and the Command String Interpreter 
(CSI), both of which may be linked with your program to provide all 
the logical capabilities required in processing dynamic terminal input 
or indirect command file input. 


2.5 OPTIMIZING FILE ACCESS 


When certain information is present in the filename block of an FDB, a 
file can be opened in a manner referred to throughout this manual as 
"opening a file by file ID." This type of open requires a minimum of 
system overhead, resulting in a significant increase in the speed of 
preparing a file for access by your program. If files are frequently 
opened and closed during program execution, opening files by file ID 
accomplishes substantial savings in overall execution time. 


To open a file by file ID, the minimum information that must be 
present in the filename block of the associated FDB consists of the 
following: 


1. File Identification Field. This 3-word field, beginning at 
filename block offset location N.FID, contains a file number 
in the first word and a file sequence number in the_- second 
word; the third word is reserved. The file identification 
field is maintained by the system and ordinarily need not be 
of concern to you. 
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2. Device Name Field. This 1l-word field at filename block 
offset location N.DVNM contains the 2-character ASCII name of 
the device on which the volume containing the desired file is 
mounted. 


3. Unit Number Field. This l-word field at filename block 
offset location N.UNIT contains a binary value identifying 
the particular unit (among several like units) on which the 
volume containing the desired file is mounted. 


These three fields are written into the filename block in one of three 
ways: 


1. As a function of issuing any version of the generalized 
OPENSx macro call for a file associated with the FDB in 
question. 


2. As a result of initializing the filename block manually by 
using the .PARSE routine (see Section 4.7.1) and the .FIND 
routine (see Section 4.8.1). 


3. You manually move the necessary values into the filename 
block. 


Opening an existing file by file ID is a special case (see Section 
349). 


2.5.1 Initializing the Filename Block As a Function of OPENSx 


To understand how to effect the process of opening a file by file ID, 
note that the initial issuance of the qeneralized OPENSx macro call 
(see Section 3.1) for a given file first invokes the .PARSE routine 
(see Section 4.7.1). The .PARSE routine is automatically linked into 
your program, along with the code for OPENSx. This routine first 
zeros the filename block and then fills it in with information taken 
from the dataset descriptor and/or the default filename biock. 


Thus, issuing the generalized OPENSx macro call results in the 
invocation of the .PARSE routine each time a file is opened. The 
-PARSE function, however, can be bypassed altogether in subsequent 
OPENSx calls by saving and restoring the filename block before 
attempting to reopen that same file. 


This is made possible because of the logic of the OPENSx macro call. 
Specifically, after the initial OPENSx for a file has been completed, 
the necessary context for reopening that file exists within the 
filename block. Therefore, before closing that file, the entire 
filename block can be copied into user memory space and later restored 
to the FDB at the desired point in program flow for use in reopening 
that same file. 


The option to reopen files in this manner stems from the fact that FCS 
is sensitive to the presence of any nonzero value in the first word of 
the file identification field of the filename block. When the OPENSx 
function is invoked, FCS first examines offset location N.FID of the 
filename block. If the first word of this field contains a value 
other than 0, FCS logically assumes that the remaining context 
necessary for opening that file is present in the filename block, and 
therefore unconditionally opens that file by file ID. 
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To ensure that an undesired value does not remain in the first word of 
the N.FID field from a previous OPENSx/CLOSE$ sequence, the first word 
of this field is zeroed as the file is closed. 


In opening files by file ID, you need only ensure that manual saving 
and restoring of the filename block are accomplished with in-line MOV 
instructions that are consistent with the desired sequence of 
processing files. This process should, in general, proceed as 
outlined below: 


1. Open the file in the usual manner by issuing the OPENSx macro 
call. 


2. Save the filename block by copying it into user memory space 
with appropriate MOV instructions. The filename block begins 
at offset location F.FNB. 


The value of the symbol S.FNB is the size of the filename 
block in bytes, and the value of the symbol S.FNBW is the 
size of the filename block in words. If desired, the NBOFSL 
macro call (see Section 2.4.2) may be invoked in your program 
to define these symbols locally. These symbolic values may 
be used in appropriate MOV instructions to accomplish the 
saving and restoring of the filename block. Moreover, you 
must reserve sufficient space in the program for saving the 
filename block. 


3. At the end of current file operations, close the file in the 
usual manner by issuing the CLOSES macro call. 


4. When, in the normal flow of program logic, that same file is 
about to be reopened, restore the filename block to the FDB 
by doing the reverse of step 2. 


5. Reopen the file by issuing any one of the macro calls 
available in FCS for opening an existing file. Since the 
first word of offset location N.FID of the filename block now 
contains a nonzero value, FCS unconditionally opens the file 
by file ID, regardless of the specific type of open macro 
call issued. 


Although it is necessary to save only the file identification, device 
name, and unit number fields of the filename block in anticipation of 
reopening a file by file ID, you are advised to save the entire 
filename block. The file name, file type, file version, and 
directory-ID fields, and so forth, may also be relevant. For example, 
an OPENSx, save, CLOSES, restore, OPENSx, and DELETS$ sequence would 
require saving and restoring the entire filename block. Though you 
may be logically finished with file processing and may want to delete 
the file, the delete operation will not work properly unless’ the 
entire filename block has been saved and restored. 


2.5.2 Manually Initializing the Filename Block 


In addition to saving and restoring the filename block in anticipation 
of reopening a file by file ID, the filename block can also be 
initialized manually. If you choose to do so, the .PARSE and _ .FIND 
routines (see Sections 4.7.1 and 4.8.1, respectively) may be invoked 
at appropriate points to build the required fields of the filename 
block. After the .PARSE and .FIND logic is completed, all the 
information required for opening the file exists within the filename 
block. When any one of the available FCS macro calls that open 
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existing files is then issued, FCS unconditionally opens that file by 
file ID. 


Occasionally, instances arise that make such manual operations 
desirable, especially if your program is operating in an overlaid 
environment. In this case, it is highly desirable that the code for 
opening a file be broken into small segments in the interest of 
conserving memory space. Since the body of code for the OPENS$x and 
-PARSE functions is sizable, two other types of macro calls for 
opening files are provided for use with overlaid programs. The OFIDS 
and OFNBS macro calls (see Sections 3.5 and 3.6, respectively) are 
specifically designed for this purpose. 


The structure recommended for an overlaid environment is to have 
either the OFIDS or the OFNBS code on one branch of the overlay and 
the .~PARSE and .FIND code on another branch. Then, if you wish to 
open a file by file ID, the .PARSE and .FIND routines can be invoked 
at will to insert required information in the filename block before 
opening the file. 


The OFID$ macro call can be issued only in connection with an existing 
file. The OFNB$ macro call, on the other hand, may be used for 
opening either an existing file or for creating and opening a new 
file. In addition, the OFNB$ macro call requires only the manual 
invocation of the .PARSE routine to build the filename block before 
opening the file. 


If conservation of memory is an objective, and if your program will be 
opening both new and existing files, it is recommended that only the 
OFNB$ routine be included in one branch of the overlay; including the 
OFID$ routine would needlessly consume memory space. 


In all cases, however, it is important to note that all the macro 
calls for opening existing files are sensitive to the presence of any 
nonzero value in the first word (N.FID) of the filename block. If 
this field contains any value other than 0, the file is 
unconditionally opened by file ID. This does not imply, however, that 
oniy the file identification field (N.FID) is required to open the 
file in this manner. The device name field (N.DVNM) and the unit 
number field (N.UNIT) must also be appropriately initialized. The 
logic of the FCS macro calls for opening existing files assumes’ that 
these other required fields are present in the filename block if the 
file identification field contains a nonzero value. 


Because many programs continually reuse FDBs, the CLOSES function (see 
Section 3.8) zeros the file identification field (N.FID) of the 
filename block. This action prevents the field (which pertains to a 
previous operation) from being used mistakenly to open a file for a 
current operation. Thus, if a user later intends to open a file by 
file ID using information presently in the filename block, the entire 
filename block (not just N.FID) must be saved before closing the file. 
Then, at the appropriate point in program flow, the filename block may 
be restored to open the desired file by file ID. 


2.6 INITIALIZING THE FILE STORAGE REGION 


The file storage region (FSR) is an area allocated in your program as 
a buffer pool to accommodate the program's block buffer requirements 
in performing record I/O (GETS and PUTS) operations. Although the FSR 
is not applicable to block I/O (READS and WRITES) operations, you must 
issue the FSRSZ$ macro once in every program that uses FCS, regardless 
of the type of I/O to be performed. 
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The macro calls associated with the initialization of the FSR are 
described below. 


2.6.1 FSRSZ$ - Initialize FSR at Assembly Time 


The MACRO-11 programmer establishes the size of the FSR at assembly 
time by issuing an FSRSZ$ macro call. This macro call does not 
generate any executable code. It merely allocates space for a 
block-buffer pool in a program section named S$$FSR1. The amount of 
Space allocated depends on information provided by you, or defaulted, 
during the macro call. 


NOTE 


The FSRSZ$ macro allocates’ the FCS 
impure area that is pointed to by a 
fixed location in user virtual memory. 
This pointer is not altered when 


overlays are loaded; therefore, the 
FSRSZS macro must be invoked in the root 
segment of a task. Unpredictable 


results may occur if the FSRSZS$ macro is 
invoked in more’ than one parallel 
overlay. 


The format of the FSRSZ$ macro is: 
FSRSZS$ fbufs,bufsiz,psect 
fbufs 
A numeric value that you establish as follows: 


1. If no record I/O processing is to be done, fbufs equals 0. 
A value of 0 indicates that an unspecified number of files 
may be open simultaneously for block I/0 processing. For 
example, if you intend to access three files for block I/0 
operations and no files for record I/O operations, the 
FSRSZ$ macro call takes 0 as an argument, as shown below: 


FSRSZ$ 0 


No other parameters need be specified unless the function 
of the psect parameter (described below) is required. 


2. If record I/O, using a single buffer for each file, is’ to 
be done, fbufs represents the maximum number of files that 
can be open simultaneously for record I/O processing. For 
example, an RSX-11M user might want to access 
simultaneously three files for block I/O and two files for 
record I/0. This user would specify the following FSRSZS$ 
macro call: 


FSRSZ$ 2 


Additional parameters, bufsiz and psect (described below), 
could also be specified as required. 


3. If record I/O with multiple buffering is to be done, fbufs 
represents the maximum number of buffers ever in use 
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Simultaneously among all files open concurrently for 
record I/O. Assume, for example, that your program will 
Simultaneously access four disk files for record I/0 
operations. Assume further that you want double-buffering 
for three of the disk files and have, therefore, specified 
a multiple buffer count of 2 in the FDBFSA macro calls 
(refer to Section 2.2.1.6) for the associated files. You 
would then issue the following FSRSZ$ macro call: 


FSRSZ$ 7 


This macro call indicates that a maximum of seven buffers 
will be in use simultaneously. This total is calculated 
as follows: one buffer for the single-buffered file and 
two buffers for each of the three double-buffered files. 
Additional parameters, bufsiz and psect (described below), 
could also be specified as required. 


bufsiz 


A numeric value defining the total block buffer pool space (in 
bytes) needed to support the maximum number of files that can be 
open simultaneously for record I/0. If this parameter is 
omitted, FCS obtains a_ total block buffer pool requirement by 
multiplying the value specified in the fbufs parameter with a 
default buffer size of 512 bytes. If, for example, a maximum of 
two single-buffered disk files will be open simultaneously for 
record I/0, either of the following FSRSZ$ macro calls could be 
issued: 


FSRSZ$ 2 
FSRSZ$ 2,1024. 


If you wish to explicitly specify block buffer pool requirements, 
the following formula must be applied: 


bsizel,bsize2,...,bsizen 


The sizes, in bytes, of the buffers to support each file. The 
Size of a buffer for a particular file depends on the device 
Supporting the file if the standard block buffer size is used. 
Standard block sizes for devices are established at system 
generation time. The override block buffer size (ovbs) 
parameter can be used in the FDBFSx macro call to increase 
buffer size, as described in Section 2.2.1.6; these increases 
must be considered when you explicitly specify block buffer 
pool requirements. 


mbcl,mbc2,...,mbcen 


The multiple buffer counts (refer to Section 2ie2s Le) 
specified for the respective files. 


The total value expressed by the bufsiz parameters must always 
represent the worst case buffer pool requirements among all 
combinations of simultaneously open record I/0 files. The 
number of files (or buffers) representing the worst case is 
expressed as the first parameter of the macro call. 
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NOTE 


An IAS or RSX-11D user must not allocate 
an FSR block buffer less than 
512(decimal) bytes in length for spooled 
output to a record-oriented device (such 
as a line printer). 


psect 


The name of the program section (PSECT) to which control returns 
after FSRSZ$ completes processing. If no name is specified, 
control returns to the blank PSECT. 


2.6.2 FINITS — Initialize FSR at Run Time 


In addition to the FSRSZ$ macro call described in the preceding 
section, the FINIT$ macro call must also be issued in a MACRO-11 
program to call initialization coding to set up the FSR. This macro 
call takes the following format: 


label: FINITS 
label 


An optional user-specified symbol that allows control to be 
transferred to this location during program execution. Other 
instructions in the program may reference this label, as in the 
case of a program that has been written so that it can be 
restarted. Considerations relative to the FINITS macro call in 
such a restartable program are presented below. 


The FINITS macro call should be issued in the program's initialization 
code. The first FCS call issued for opening a file performs the FSR 
initialization implicitly (if it has not already been accomplished 
through an explicit invocation of the FINIT$ macro call). However, it 
is necessary, in the case of a program that is written so that it can 
be restarted, to issue the FINIT$ macro call in the program's 
initialization code, as shown in the second example below. This 
requirement derives from the fact that such a program performs all its 
initialization at run time, rather than at assembly time. 


For example, a program that is not written so that it can be restarted 
might accomplish the initialization of the FSR implicitly through the 
following macro call: 


START: OPENSR #FDBIN ; IMPLICITLY INITIALIZES THE FSR 
AND OPENS THE FILE. 


In this case, although transparent to you, the OPENSR macro call 
automatically invokes the FINITS operation. The label START is the 
transfer address of the program. 


In contrast, a program that embodies the capability to be restarted 
must issue the FINITS macro call explicitly at program initialization 
in the manner shown below: 


START: FINITS EXPLICITLY INITIALIZES THE FSR AND 
OPENSR #FDBIN ;OPENS THE FILE. 
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In this case, the FINIT$ macro call cannot be invoked arbitrarily 
elsewhere in the program; it must be issued at program 
initialization. Doing so forces the appropriate reinitialization of 
the FSR, whether or not it has been done in a previous execution of 
the program through an OPENSx macro call. 


Also important in the above context is the fact that calling any of 
the file control routines described in Chapter 4, such as .PARSE, 
first requires the initialization of the FSR. However, the FINITS 
operation must be performed only once each program execution. Note 
also that FORTRAN programs issue a FINIT$ macro call at the beginning 
of the program execution; therefore, MACRO-11 routines used with the 
FORTRAN object time system must not issue a FINITS macro call. 


2.7 INCREASING THE SIZE OF THE FILE STORAGE REGION 


Procedures for increasing the size of the FSR for either MACRO-11 or 
FORTRAN programs are presented in the following sections. 


2.7.1 FSR-Extension Procedures for MACRO-11 Programs 


To increase the size of the FSR for a MACRO-1l program, you have two 
options: 


1. Modify the parameters in the FSRSZ$ macro call to redefine 
the buffer pool requirement of files open simultaneously for 
record I/O processing. Reassemble the program. 


2. Use the EXTSCT (extend program section) command at task-build 
time to define the new size of the FSR. To invoke this 
option, the command is specified in the following form: 

EXTSCT = $$FSR1:length 
SSFSR1 

The symbolic name of the program section within the FSR that is 

reserved for use as the block buffer pool length. A numeric 

value defining the total required size of the buffer pool in 
bytes. 

The size of the FSR cannot be reduced at task-build time. 


In calculating the total length of the FSR, you can use either of the 
formulas below: 


1. Length = (S.BFHD*fbufs)+bufsiz 
2. Length = fbufs*(S.BFHD+512.) 
S.BFHD 


A symbol that defines the number of bytes required for each block 
buffer header. If desired, you can define this symbol locally in 
your program by issuing the following macro call: 


BDOFFS$ DEFSL 
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fbufs 


A numeric value representing either the maximum number of files 
open simultaneously for record I/O (when single buffering only is 
used) or the maximum number of buffers ever in use simultaneously 
among all files open concurrently for record I/O (when multiple 
buffering is used). Refer also to the description of this 
parameter in the FSRSZ$ macro call in Section 2.6.1. 


bufsiz 


A numeric value defining the total block buffer pool space (in 
bytes) needed to support the maximum number of files that can be 
open simultaneously for record I/O. Refer to the description of 
this parameter in the FSRSZ$ macro call in Section 2.6.1. 


512. 
The standard default buffer size. 


The EXTSCT command is described in detail in the Task Builder 
Reference Manual of the host operating system. 


2.7.2 FSR-Extension Procedures for FORTRAN Programs 


For a FORTRAN program, if an explicit ACTFIL statement is not issued 
in the optional keyword input to the Task Builder, an ACTFIL statement 
with a default value of 4 is generated automatically during task 
build. To extend the size of the FSR at task-build time, you can 
issue the following command: 


ACTFIL. = files 
files ' 


A decimal value defining the maximum number of files that may be 
open simultaneously for record I/O processing. 


This command, Similar to the EXTSCT command above, causeS program 
section S$SFSR1 to be extended by an amount sufficient to accommodate 
the number of active files anticipated for simultaneous use by the 
program. 


The size of the FSR for a FORTRAN program can also be decreased at 
task-build time. As noted above, for either IAS or RSX-11, the 
default value for the ACTFIL command is 4. Thus, if 0, 1, 2, or 3 is 
specified as the "files" parameter, the size of $$FSR1 (the FSR block 
buffer pool) is reduced accordingly. 


The ACTFIL command is described in detail in the Task Builder 
Reference Manual of the host operating system. 


2.8 COORDINATING I/O OPERATIONS 


In the IAS/RSX-11 environment, user programs perform all 1/0 
operations by issuing GETS$S/PUT$ and READS/WRITES macro calls (see 
Chapter 3). These calls do not access the physical devices in the 
system directly. Rather, when any one of these calls is issued, an 
I/O-related system directive called QUEUE I/0 is invoked as_ the 
interface between the FCS file-processing routines at the user level 
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and the system I/O drivers at the device level. Device drivers are 
included for all the standard I/O devices supported by IAS and RSX-11l 
systems. Although transparent to the user, the QUEUE I/O directive is 
used for all FCS file access operations. 


When invoked, the QUEUE I/O directive instructs the system to place an 
I/O request for the associated physical device unit into a queue of 
priority-ordered requests for that unit. This request is_ placed 
according to the priority of the issuing task. As required system 
resources become available, the requested I/O transfer takes place. 


As implied above, two separate and distinct processes are involved in 
accomplishing a specified I/O transfer: 


1. The successful queuing of the GETS/PUTS or READS/WRITES I/0 
request 


2. The successful completion of the requested data transfer 
operation. 


These processes, both of which yield success/failure indications that 
may be tested by your program, must be performed successfully in order 
for the specified I/0 operation to have been completed. It is 
important to note that FCS totally synchronizes record I/O operations 
for you, even in the case of multiple-buffered operations. In the 
case of block I/0 operations, the flexibility of FCS allows you to 
synchronize all block I/O activities, thus enabling you to. satisfy 
logical processing dependencies within the program. 


2.8.1 Event Flags 


I/O operations proceed concurrently with other system activity. After 
an I/O request has been queued, the system does not force an implied 
wait for the issuing task until the requested operation is completed. 
Rather, the operation proceeds in parallel with the execution of the 
issuing task, and it is the task's responsibility to synchronize the 
execution of I/0 requests. Tasks use event flags in synchronizing 
these activities. With respect to event flags, the system merely 
executes primitive operations that manipulate, test, and/or wait for 
these indicators of internal task activity. 


The completion of an I/O transfer, for example, is recognized by the 
System aS a Significant event. If you have specified a particular 
event flag to be used by the task in coordinating I/O-completion 
processing, that event flag is set, causing the system to evaluate the 
eligibility of other tasks to run. Any event flag from 1 through 
32(decimal) may be defined for local use by the task. If you have not 
specified an event flag, FCS uses event flag 32(decimal) by default to 
signal the completion of I/O transfers. 


Specific FDB-initialization and I/O-initiating macro calls in FCS 
enable you to specify event flags, if desired, that are unique to a 
particular task and that are set and reset only as a result of that 
task's operation. 


For record I/O operations, such an event flag may be defined through 
the efn parameter of the FDBFSA or the FDBFSR macro call (see Section 
2.2.1.6 or 2.2.2, respectively). 


For block I/O operations, an event flag may be declared through the 


bkef parameter of the FDBKSA or the FDBKSR macro call (see Section 
2.2.1.4 or 2.2.2, respectively); alternatively, a block event flag 


2-42 


PREPARING FOR I/O 


may be declared through the corresponding parameter of the 
I/O-initiating READS or WRITES macro call (see Section 3.15 or 3.16, 
respectively). 


In both record and block I/O operations, the event flag is cleared 
when the I/O request is queued and set when the I/O operation is 
completed. In the case of record I/O operations, only FCS manipulates 
the event flag. Additionally, the event flag's state is transparent 
to the user, who must not issue a WAITFOR system directive predicated 
on the event flag used for coordinating record I/O operations. A 
record I/O operation, for example, may not even involve an I/O 
transfer; rather, it may only involve the blocking or deblocking of a 
record within the FSR block buffer. On the other hand, the event flag 
defined for synchronizing block I/O operations is totally under your 
control. 


Also, a code indicating the success or failure of the QUEUE I/0 
request resulting from the READS/WRITES macro call is returned to the 
Directive Status Word (S$DSW). If desired, symbolic location SDSW may 
be tested to determine the status of the I/0 request. The 
success/failure codes for the QUEUE I/O directive are listed in the 
manuals referenced above. 


Event flag directives are described in the RSX-11M/M-PLUS Executive 
Reference Manual. The relationship of event flags to specific devices 
is described in the RSX-11M/M-PLUS I/O Drivers Reference Manual. 


2.8.2 I/0 Status Block 


Because of the comparative complexity of block I/0 operations, an 
optional parameter is provided in the FDBKSA and the FDBKSR macro 
calls, as well as in the READS and WRITES macro calls, that enables 
the system to return status information to your task for block I/0 
operations. The I/O status block is not applicable to record I/0 
(GETS or PUTS) operations. 


This optional parameter, called the I/O status block address, is made 
available to FCS through any of the macro calls identified above. 
When this parameter is supplied, the system returns status information 
to a 2-word block reserved in your program. Although the I/O status 
block is used principally as a QUEUE I/O housekeeping mechanism for 
containing certain device-dependent information, this area also 
contains information of particular interest to you. 


Specifically, the second word of the I/O status block is filled in 
with the number of bytes transferred during a READS or WRITES 
operation. When you are performing READS operations, it is good 
practice always to use the value returned to the second word of the 
I/O status block as the number of bytes actually read, rather than to 
assume that the requested number of bytes was transferred. Employing 
this technique allows the program to properly read virtual blocks of 
varying length from a device such as a magnetic tape unit, provided 
that the requested byte count is at least as large as the largest 
virtual block. For WRITES operations, the specified number of bytes 
are always transferred; otherwise, an error condition exists. 
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Also, the low-order byte of the first word of the I/0 status’ block 
contains a code that reflects the final status of the READS/WRITES 
operation. The codes returned to this byte may be tested to determine 
the status of any given block I/O transfer. The binary values of 
these status codes always have the following significance: 


Code Value Meaning 
+ I/O transfer completed. 
0 I/O transfer still pending. 


- I/O error condition exists. 


The format of the I/O status block and the error codes returned to the 
low-order byte of its first word are described in detail in the IAS 
Device Handlers Reference Manual or the RSX-11M/M-PLUS I/O Drivers 
Reference Manual. 


If the address of the I/O status block is not made available to FCS 
(and hence to the QUEUE I/O directive) through any of the macro calls 
noted above, no status information is returned to the I/O status 
block. In this case, the fact that an error condition may have 
occurred during a READS or WRITES operation is simply lost. Thus, 
supplying the address of the I/O status block to the associated FDB is 
highly desirable in order to facilitate normal error reporting. 


An I/O status block may be defined in the user program at assembly 
time through any storage directive logically equivalent to the 
following: 


IOSTAT: .~BLKW 2 
IOSTAT 


A user-defined symbol naming the I/O status block and defining 
its address. This symbolic value is specified as the bkst 
parameter in the FDBKSA or the FDBKSR macro call to initialize 
FDB offset location F.BKST; it may also be specified as the 
corresponding parameter in the READS or the WRITES macro call. 
Initializing this cell in the FDB is an integral part of issuing 
the desired I/O request. 


2.8.3 AST Service Routine 


An asynchronous system trap (AST) is a software-generated interrupt 
that causes the sequence of instructions currently being executed to 
be interrupted and control to be transferred to another instruction 
sequence elsewhere in the program. If desired, you may specify the 
address of an AST service routine that is to be entered upon 
completion of a block I/O transfer. Since an AST is a trap action, it 
constitutes an automatic indication of block I/0O completion. 


The address of an AST service routine may be specified as an optional 
parameter (bkdn) in the FDBKSA or the FDBKSR macro call (see Section 
2.2.1.4 or 2.2.2, respectively); this parameter may also be specified 
in the READS or the WRITES macro call, initializing the FDB at the 
time the I/0 request is issued (see Section 32k5 or 3016; 
respectively). 
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Usually, an AST address is specified to enable a running task to be 
interrupted in order to execute special code upon completion of a 
block I/O request. If the address of an AST service routine is not 
specified, the transfer of control does not occur, and normal task 
execution continues. 


The main purpose of an AST service routine is to inform the user 
program that a block I/O operation has been completed, thus enabling 
the program to continue immediately with some other desired (and 
perhaps logically dependent) operation (for example, another I/0 
transfer). 


If an AST service routine is not provided by the user, some other 
mechanism, such as event flags or the I/O status block, must be used 
as a means of determining block I/O completion. In the absence of 
such a_ routine, for example, the user may test the low-order byte of 
the first word in the I/O status block to determine if the block I/0 
transfer has been completed. A WAITS macro call (see Section 3.17) 
may also be issued in connection with a READS or WRITES operation to 
suspend task execution until a specified event flag is set to indicate 
the completion of block I/0. 


Implementing an AST service routine in the user program is application 
dependent and must be coded specifically to meet particular user 
I/O-processing requirements. A detailed discussion of asynchronous 
system traps is beyond the scope of this document. Refer to the 
Executive Reference Manual of the host operating system for 
discussions of trap-associated system directives. 


WARNING 


Do not execute any FCS routines while in 
an AST service routine. FCS maintains 
an impure data area that it useS as a 
Directive Parameter Block and aS a 
scratch area for directives. An AST 
could interrupt an FCS operation that is 
altering this impure area. Executing an 
FCS routine in AST state could alter the 
impure area and cause unpredictable 
results when task execution resumes. 
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FILE-PROCESSING MACRO CALLS 


You manipulate files through a set of file-processing macro calls. 
These macro calls are invoked and expanded at assembly time. The 
resulting code is then executed at run time to perform the operations 
listed below: 


OPENS - To open and prepare a file for processing 

OPNSS$ - To open and prepare a file for processing and to allow 
shared access to that file (depending on the mode of 
access) 

OPNTS - To create and open a temporary file for processing 

OFIDS - To open an existing file using file identification 


information in the filename block 


OFNBS - To open a file using file name information in the 
filename block 


CLOSE$ - To terminate file processing in an orderly manner 

GETS - To read logical data records from a file 

GETSR - To read fixed-length records from a file in random mode 

GETSS - To read records from a file in sequential mode 

PUTS - To write logical data records to a file 

PUTSR - To write fixed-length records to a file in random mode 

PUTSS - To write records to a file in sequential mode 

READS - To read virtual data blocks from a file 

WRITES - To write virtual data blocks to a file 

DELETS$ - To remove a named file from the associated volume 
directory and to deallocate the space occupied by the 
file 

WAITS - To suspend program execution until a requested block 


I/O operation is completed 


Most of the parameters associated with the file-processing macro calls 
supply information to the FDB. Such parameters cause MOV or MOVB 
instructions to be generated in the object code, resulting in the 
initialization of specific locations within the FDB. 
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The final parameter in all file-processing macro calls is the symbolic 
address of a user-coded, error-handling routine. This routine is 
entered upon detection of an error condition during the 
file-processing operation. When this optional parameter is specified, 
the following code is generated: 


Code for macro 


BCC nn$ ;TESTS C-BIT IN PROCESSOR STATUS WORD. 
JSR PC, ERRLOC ; INITIATES ERROR-HANDLING ROUTINE 
;AT "“ERRLOC" ADDRESS. 
nns$: CONTINUES NORMAL PROGRAM EXECUTION. 


where nn$ represents an automatically generated local symbol. If the 
operation is completed successfully, the C-bit (carry condition code) 
in the Processor Status Word is not set, and FDB offset location F.ERR 
contains a positive value. The BCC instruction then results in a 
branch to the local symbol nn$ and the continuation of normal program 
execution. 


However, if an error condition is detected during the execution of the 
file-processing routine, the C-bit in the Processor Status Word is 
set, FDB offset location F.ERR contains a negative value (indicating 
an error condition), and the branch to the local symbol nn$ does not 
occur. Instead, the JSR instruction is executed, loading the PC with 
the symbolic address (ERRLOC) of the error-handling routine and 
initiating its execution. 


If this optional parameter is not specified, the error-processing 
routine is not called, and you must explicitly test the C-bit in the 
Processor Status Word to ascertain the status of the requested 
operation. 


Note that executing the FCS file-processing routines causes all 
user-program general registers to be saved except RO, which by 
convention is used by FCS to contain the address of the FDB associated 
with the file being processed. 


3.1 OPENSX - GENERALIZED OPEN MACRO CALL 


Before any file can be processed by your (or system) program, it must 
first be opened. The type of action that you intend to perform on a 
file is indicated to FCS by an alphabetic suffix accompanying the 
macro name. For example, in issuing the generalized macro call 


OPENSx 


x represents any one of the following alphabetic suffixes, each of 
which denotes a specific type of processing anticipated for the file: 


R - Read an existing file 

W - Write (create) a new file 

M - Modify an existing file without changing its length 

U - Update an existing file and extend its length, if necessary 
A - Append (add) data to the end of an existing file 
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NOTE 


You can issue the generalized OPENSx 
macro call without an alphabetic suffix. 
In this case, the type of action to be 
performed on the file is indicated to 
FCS through an additional parameter in 
the macro call. This value, called the 
file access (facc) parameter, causes 
offset location F.FACC in the associated 
FDB to be initialized. Section 3.7 
describes this macro call in detail. 


Depending on the alphabetic suffix supplied in the OPENSx macro call, 
certain other types of operations may or may not be allowed, as noted 
below: 


1. If R is specified (for reading an existing file), that file 
cannot also be written; that is, a PUTS or WRITES operation 
cannot be performed on that file. 


2. If Mor U is specified (for modifying or updating an existing 
file), that file can be both read and written; that is, 
concurrent GETS/PUT$ or READS/WRITES operations can be 
performed on that file. 


3. If M is specified (for modifying an existing file), that file 
cannot be extended. 


4, If Wor A is specified (for creating a new file or appending 
data to an existing file), that file can be read, written, 
and/or extended. 

The program that is issuing the OPENSx macro call must have 
appropriate access privileges for the specified action. Table 3-l 
Summarizes the access privileges for the various forms of the OPENSx 


Macro call. This table also shows where the next record or block will 
be read or written in the file after it is opened. 


Table 3-1 
File Access Privileges Resulting from OPENS$x Macro Call 


MACRO ACCESS PRIVILEGES POSITION OF FILE AFTER OPENSx 


OPENSR First f existing file 
OPENSW write, extend First 
OPENSM write First existing file 


OPENSU write, extend First of existing file 


OPENSA write, extend End of existing file (For 
special PUTSR considerations, 
see Section 3,13.) 


When any form of the OPENSx macro call is issued, FCS first fills in 
the filename block with file name information retrieved from the 
dataset descriptor (see Section 2.4.1). FCS gains access to this data 
structure through the address value stored in FDB offset location 
F.DSPT. 
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If any required data has been omitted from the dataset descriptor, FCS 
attempts to obtain the missing information from the default filename 
block. This data structure, which may also contain user-specified 
file name information, is created in the program by issuing the NMBLKS 
macro call (see Section 2.4.2). FCS gains access to this structure 
through the address value stored in FDB offset location F.DFNB. 


The address values in offset locations F.DSPT and F.DFNB can be 
supplied to FCS through the FDOPSA macro call, the FDOPSR macro call, 
or the OPENSx macro call. FCS requires access to the dataset 
descriptor and/or the default filename block in retrieving file name 
information used in opening files. 


If a new file is to be created, the OPENSW macro call is issued. FCS 
then performs the following operations: 


1. Creates a new file and obtains file identification 
information for the file. FCS Maintains the file 
identification information in offset location N.FID of the 
filename block. The filename block in the FDB begins at 
offset location F.FNB. 


2. Initializes the file attribute section of the file header 
block. The file header block is a file system structure 
maintained on the volume containing the file. Each file ona 
volume has an associated file header block that describes the 
attributes of that file. FCS obtains attribute information 
for a new file from the FDB associated with the file. The 
format and content of a file header block are presented in 
detail in Appendix F. 


3. Places an entry for the file in the User File Directory 
(UFD). If, however. an entry for a file having the same 
name, type, and version number already exists in the UFD, the 
old file is deleted. If a particular type of macro call is 
issued explicitly specifying that the file not be superseded, 
the old file is not deleted and an error code is returned. 
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4. Associates the assigned logical unit number (LUN) with the 
file to be created. 


5. Allocates a buffer for the file from the FSR block buffer 
pool if record I/O (GETS$/PUTS$) operations are to be used in 
processing the file. 


If an existing file is to be opened, any one of the following macro 
calls may be issued: OPENSR, OPENSM, OPENSU, or OPENSA. FCS then 
performs the following operations: 


1. If file identification information is not present in the file 
name block, FCS constructs the filename block from 
information taken from the dataset descriptor and/or the 
default filename block. FCS then searches the UFD by file 
name to obtain the required file identification information. 
When found, this information is stored in the filename block, 
beginning at offset location N.FID. 


2. Associates the assigned logical unit number {LUN) with the 
file. 


3. Reads the file header block and initializes the file 


attribute section of the FDB associated with the file being 
opened. 
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4. Allocates a buffer for the file from the FSR block buffer 
pool if record I/O (GETS$/PUT$) operations are to be used in 
processing the file. 


NOTE 


As described in Section 2.6, you 
allocate buffers through the FSRSZ$ 
macro call. The number of buffers 
allocated is dependent upon the number 
of files that you intend to open 
Simultaneously for record I/o 
operations. 


If block I/O operations are to be used, 
FDB offset location F.RACC must be 
initialized with the FD.RWM parameter by 
the FDRCSA, the FDRCSR, or the 
generalized OPENS$x macro call. This 
parameter inhibits the allocation of a 
buffer when the file is opened. 


Format of Generalized OPENSx Macro Call 


The generalized macro call for opening files takes the following form: 


fdb 


lun 


dspt 


OPENSx fdb,lun,dspt,racc,urba,urbs,err 


The alphabetic suffix specified as part of the macro name, 
indicating the desired type of operation to be performed on the 
file. The possible values for this parameter are: R, W, M, U, 
or A (see Section 3.1). 


A symbolic value of the address of the associated FDB. 


The logical unit number (LUN) associated with the desired file. 
This parameter identifies the device on which the volume 
containing the desired file is mounted. Normally, the logical 
unit number associated with the file is specified through the 
corresponding parameter of the FDOPSA or the FDOPSR macro call. 
If so specified, the lun parameter need not be present in the 
OPENSx macro call. Each FDB must have a unique LUN. 


The symbolic address of the dataset descriptor. Normally, this 
address value is specified through the corresponding parameter of 
the FDOPSA or the FDOPSR macro call. If so specified, this 
parameter need not be present in the OPENSx macro call. 


racc 


urba 
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This parameter specifies the address of the manually created 
dataset descriptor (see Section 2.4.1). If the Command String 
Interpreter (CSI) is being used to interpret command lines 
dynamically, this parameter is used to specify the address of the 
dataset descriptor within the CSI control block (see offset 
location C.DSDS in Section 6.2.2). 


The record access byte. One or more symbolic values may be 
specified in this field tto initialize the record access byte 
(F.RACC) in the associated FDB. You can specify any combination 
of the following parameters by separating them with exclamation 
points: 


e FD.RWM - Indicates that block I/O (READS/WRITES) operations 
are to be used in processing the file. If this parameter 
is not specified, FCS assumes by default that record I/0 
(GETS/PUTS) operations are to be used in processing the 
file. 


e FD.RAN - Indicates that random access to the file is to be 
used for record I/0 (GETS$/PUT$) operations. If this 
parameter is not specified, FCS uses sequential access by 
default. Refer to Section 1.5 for a description of random 
access mode. 


e FD.PLC - Indicates that locate mode (see Section 1.6.2) is 
to be used for record I/O (GETS/PUTS$) operations. If this 
parameter is not specified, FCS uses move mode (see Section 
1.6.1) by default. 


tt 
ty 


_—— 


the body of a file shall not truncate the file. 
Effectively, this parameter prevents the logical end of the 
file from being reset to a point just beyond the inserted 
record. If this parameter is not specified, a PUTS 
operation in sequential mode truncates the file to a point 
just beyond the inserted record, but no deallocation of 
file blocks occurs. 


D.INS - Indicates that a PUTS operation in sequential mode 
n 


Specifying this parameter allows a data record in the body of the 
file to be overwritten. Care must be exercised, however, to 
ensure that the record being written is the same length as that 
of the record being replaced. 


If the FD.RAN parameter above is specified, the file is accessed 
in random mode. In this case, a PUTS operation in the file, 
without exception, does not truncate the file. 


If the record access byte in the FDB has already been initialized 
through the corresponding parameters of the FDRCSA or the FDRCSR 
macro call, the racc parameters need not be present in the OPENSx 
macro call. 


The symbolic address of the user record buffer. This parameter 
initializes FDB offset location F.URBD+2. 


If the user record buffer address has already been supplied _ to 
the FDB through the corresponding parameter of the FDRCSA or the 
FDRCSR macro call, this parameter need not be present in the 
OPENSx macro call. 
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urbs 


A numeric value defining the size of the user record buffer (in 
bytes). This parameter initializes FDB offset location F.URBD. 


If the size of your record buffer has already been supplied to 
the FDB through the corresponding parameter of the FDRCSA or the 
FDRCSR macro call, this parameter need not be present in the 
OPENSx macro call. 


err 


The symbolic address of an optional user-coded, error-handling 
routine. 


Specific FDB requirements for record I/O operations (GETS and PUTS 
macro calls) are detailed in Sections 3.9.2 and 3.12.2. 


The following examples depict representative uses of the OPENSx macro 
call. 


A macro call to open and modify an existing file, for example, might 
take the following form: 


OPENSM RO,#INLUN,,#FD.RAN! FD. PLC 


Note in this macro call that the FDB address is assumed to be present 
in RO. The third parameter, that is, the dataset descriptor pointer, 
is not specified: this null specification (indicated by the extra 
comma) assumes that FDB offset location F.DSPT (if required) has 
already been initialized. The last parameter, consisting of two 
values separated by an exclamation point, establishes random access 
and locate modes for GETS/PUTS operations. 


The following macro call might be issued to update an existing file: 
OPENSU RO,#INLUN,,,#RECBUF,#80. 


This macro call also assumes that the FDB address is in RO. Note also 
that the dspt and racc parameter fields are null, based on the premise 
that the dataset descriptor pointer (F.DSPT) has been provided 
previously to the FDB and that the record access byte (F.RACC) has 
also been previously initialized. Finally, the last two parameters 
establish the address and the size, respectively, of the user record 
buffer. 


This last example shows a macro call that might be issued to allow 
data to be appended to the end of a file: 


OPENSA #0OUTFDB 


This macro call specifies the address of an FDB as the only parameter. 
In this case, it is assumed that all other parameters required by FCS 
in opening and operating on the file have been previously supplied to 
the FDB through the appropriate assembly-time or run-time macro calls. 


Note in all three examples above that the error parameter is not 
specified, requiring that you explicitly test the C-bit in the 
Processor Status Word to aScertain the success of the _ specified 
operation. 


NOTE 


You can use RO only to pass the _ FDB 
address parameter. Any other use of RO 
when you issue the OPENSA macro call 
will fail. 


3.1.2 FDB Requirements for Generalized OPENSx Macro Call 


The information required for opening a file may be supplied to the FDB 
through the following macro calls: 


e The assembly-time macro calls described in Section 2.2.1 
e@e The NMBLKS macro call described in Section 2.4.2 
e The run-time macro calls described in Section 2.2.2 


e The various macro calls described in this chapter for opening 
files 


The particular combination of macro calls used to define and 
initialize the FDB is a matter of choice, as indicated above. Of far 
greater significance is the fact that certain information must be 
present in the FDB before the associated file can be opened. In this 
regard, the following rules apply for creating and opening new files, 
for opening existing files, and for specifying desired file options: 


1. To Create a New File. If a new file is to be created through 
the OPENSW macro call, the following information must first 
be supplied to the FDB. You can specify this information 
through the FDATSA macro call (see Section 2.2.1.2) or the 
FDATSR macro call (see Section 2.2.2): 


ae The record type must be established for record I/0 
operations. To accompiish this, you must initialize byte 
offset location F.RTYP with the following symbolic 
values: 


e R.FIX - Indicates that fixed-length records are _ to 
be written into the file 


e R.VAR - Indicates that variable-length records are 
to be written into the file 


e R.SEQ - Indicates that sequenced records are to be 
written into the file 


b. The desired record attributes must be specified for 
record I/O operations. The record attributes are defined 
by initializing byte offset location F.RATT with the 
appropriate value(s), as follows: 


e FD.FTN - Indicates that the first byte of each 


record is to contain a FORTRAN carriage control 
character. 
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e FD.CR - Indicates that a line-feed (<LF>) character 
is to precede each record and that a carriage 
return (<CR>) character is to follow the record 
when that record is output to a device requiring 
carriage control information (for example, to a 
terminal). The <LF> and <CR> characters are not 
actually embedded within the record. Their 
presence is merely implied through the file 
attribute FD.CR. 


e FD.BLK - Indicates that records are not allowed to 
cross block boundaries. 


e FD.PRN - Indicates that the record is preceded by a 
word containing carriage control information. 


c. If fixed-length records are to be written to the file, 
you must specify the record size (in bytes) for record 
I/O operations to appropriately initialize FDB offset 
location F.RSIZ. 


Items a. through c. above cannot be supplied to the FDB 
through any of the various macros used to create and/or open 
files (for example, OPENSW, OPENSR, and so forth). 
Furthermore, none of the above information is required when 
opening an existing file, since FCS obtains such information 
from the first 14 bytes of the user file attribute section of 
the file header block (see Appendix F). 


To Open Either a New File or an Existing File. Regardless of 
whether the file being opened is yet to be created or already 
exists, the following information must be present in the FDB 
before that file can be opened: 


a. The record access byte must be initialized for 
record/block I/O operations. The symbolic values below 
may be specified in the FDRCSA macro call (see Section 
2.2.1.3), the FDRCSR macro call (see Section 2.2.2), or 
the generalized OPENSx macro call to initialize FDB 
offset location F.RACC: 


e FD.RWM - Indicates that READS/WRITES (block I/0) 
operations are to be used in processing the file. 
If this parameter is not specified, GETS$/PUTS 
(record I/O) operations result by default. 


e FD.RAN - Indicates that random access mode 
(GETS/PUT$ record I/O) is to be used in processing 
the file. If this parameter is not specified, 
sequential access mode results by default. Refer 
to Section 1.5 for a description of random access 
mode. 


e FD.PLC - Indicates that locate mode (GETS$S/PUTS 
record I/0) is to be used in processing the file. 
If this parameter is not specified, move mode 
results by default. 


e FD.INS - Indicates that a PUTS operation in 
sequential mode in the body of a file shall not 
truncate the file. If this parameter is not 
specified, such an operation truncates the file. 
In this case, the logical end of the file is reset 
to a point just beyond the inserted record, but no 
deallocation of file blocks occurs. 


b. Your record buffer descriptors, (that is, the urba and 
urbs parameters), must be specified for record I/0 
operations. To accomplish this, the FDRCSA, the FDRCSR, 
or the generalized OPENSx macro call may be used. The 
selected macro call defines the address and the size of 
the area reserved in the program for use as a buffer 
during record I/O operations. The urba and urbs 
parameters initialize FDB offset locations F.URBD+2 and 
F.URBD, respectively. 


FDB requirements specific to GETS$ and PUTS operations in 
move and locate mode are presented in detail in Sections 
3.9.2 and 3.12.2, respectively. 


c. You must specify the logical unit number to initialize 
FDB offset location F.LUN. Initializing this cell can be 
accomplished with the lun parameter of the FDOPSA, the 
FDOPSR, or the generalized OPENS$Sx macro call. Each FDB 
must have a unique logical unit number. 


d. If file identification information is not already present 
in the FDB, either the dataset descriptor pointer 
(F.DSPT) or the default filename block address (F.DFNB) 
must be specified to enable FCS to obtain required file 
name information for use in opening the file. These 
address values may be specified in either the FDOPSA 
macro call (see Section 2.1.1.5) or the FDOPSR macro call 
(see Section 2.2.2). The generalized OPENSx macro call 
(see Section 3.1) may also be used to specify the dataset 


ed ~~ sate 


e. If desired, an event flag number for synchronizing record 
I/O operations must be specified to initialize FDB offset 
location F.EFN. This optional parameter may be specified 
in either the FDBFSA macro call (see Section 2.2.1.6) or 
the FDBFSR macro call (see Section 2.2.2). Tf not 
specified, FCS uses event flag number 32(decimal) by 
default in synchronizing all record I/O activity. 


Specifying Desired File Options. If certain options are 
desired for a given file, they must be specified before that 
file is opened. Since this information is needed only in 
opening the file, it is zeroed when the file is closed, thus 
ensuring that the FDB is properly reinitialized for 
subsequent use. The options that may be specified for a 
given file are described below: 


a. The override block size (ovbs parameter) must be 
specified in either the FDBFSA or the FDBFSR macro call 
to initialize FDB offset location F.OVBS. This parameter 
need be specified only if the standard default block size 
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in effect for the associated device is to be overridden 
or if the big-buffering or multiple-buffering versions of 
FCS are in use. The override block size is specified to 
improve I/O system throughput with record I/O, and with 
record-oriented devices (such as line printers) and 
sequential devices (such aS magnetic tape units). (See 
Section 2.2.1.6.) 


The multiple buffer count (mbct parameter) must be 
specified in either the FDBFSA or the FDBFSR macro call 
to initialize FDB offset location F.MBCT. If 
multiple-buffered record I/0 operations are to be used, 
this parameter must be greater than 1, and it must agree 
with the desired number of buffers to be used. This 
parameter is not overlaid, nor is it zeroed when the file 
is closed. 


If the multiple buffer count is not established as 
described above, multiple-buffered operations can still 
be invoked by changing the default buffer count in the 
FSR. A default buffer count of 1 is stored in symbolic 
location .MBFCT of SSFSR2. This default value can be 
altered to reflect the number of buffers intended for use 
during record I/O operations. The procedure for 
modifying this cell in $$FSR2 is described at the end of 
Section 2.2.1.6. 


In addition, if multiple buffering is to be employed, the 
appropriate control flag must be specified as the mbfg 
parameter in either the FDBFSA or the FDBFSR macro call 
to appropriately initialize FDB offset location F.MBFG. 
Either of two symbolic values may be specified for this 
purpose, as follows: 


e FD.RAH — Indicates that read-ahead operations are 
to be used in processing the file. 


e FD.WBH - Indicates that write-behind operations are 
to be used in processing the file. 


Offset location F.MBFG need be initialized only if the 
standard default buffering assumptions are inappropriate. 
When a file is opened for reading (OPENSR), read-ahead 
operations are assumed by default; for all other forms 
of OPENSx, write-behind operations are assumed. It may 
be useful, for example, to override the write-behind 
default assumption for a file opened through the OPENSM 
or the OPENSU macro call when that file is being used 
basically for sequential read operations, but scattered 
updating is also being performed. 


To allocate required file space at the time a file is 
created, the cntg parameter must be specified in either 
the FDATSA or the FDATSR macro call. This parameter 
initializes FDB offset location F.CNTG. A positive value 
so specified results in the allocation of a contiguous 
file having the specified number of blocks; a negative 
value, on the other hand, results in the allocation of a 
noncontiguous file having the specified number of blocks. 
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d. The address of the 5-word statistics block in your 
program must be moved manually into FDB offset location 
F.STBK. This address value specifies an area in the user 
program to which FCS returns certain statistical 


information about a file when it is opened. If this 
parameter is not specified, no return of such information 
occurs. 


The format and content of the statistics block are 
presented in Appendix H. You can define such an area in 
a program with coding logically equivalent to that shown 
below: 


STBLK: .BLKW 5 


Offset location F.STBK may then be manually initialized, 
as follows: 


MOV #STBLK, FDBADR+F.STBK 


where STBLK is the user-defined symbolic address of the 
statistics block, and the destination operand of this 
instruction defines the appropriate offset location 
within the desired FDB. 


3.2 OPNSSX - OPEN FILE FOR SHARED ACCESS 


The OPNSSx macro call is issued to open a file for shared access. 
This macro call has the same format, that is, takes the same 
alphabetic suffixes and run-time parameters, as the generalized OPENSx 
macro call. The shared access conditions that result from the use of 
this macro call are summarized in Section 1.8. 


3.3 OPNTSW - CREATE AND GPEN TEMPORARY FILE 


The OPNTSW macro call is issued to create and open a temporary file 
for some special purpose of limited duration. If a temporary file is 
to be used only once, it is best created through the OPNTSD macro call 
described in the following section. 


The OPNTSW macro call creates a file but does not enter a file name 
for that file into any associated user directory file. 


In using the OPNTSW macro call, you bear the responsibility for 
marking the temporary file for deletion, as described in the procedure 
below. Then, after all operations associated with that file are 
completed, closing the file results in its deallocation. All space 
formerly occupied by the file is then returned for reallocation to the 
pool of available storage on the volume. 


Although the OPNTSW macro call takes the same parameters as those of 
the generalized OPENS$x macro call, the former executes faster because 
no directory entries are made for a temporary file. 


Creating a temporary file is usually done when a program requires a 
file only for the duration of its execution (for example, for use as a 
work file). The general sequence of operations in such instances 
proceeds as follows: 
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1. Open a temporary file by issuing the OPNTSW macro call. 
Perform any desired operations on that file. If the file is 
to be used only for a single OPNTSW/CLOSE$ Sequence, go to 
step 6; otherwise, continue with step 2. 


2. Before closing the file for processing, save the filename 
block in the associated FDB. The general procedure for 
saving (and restoring) the filename block is discussed in 
Section 2.5.1. 


3. Close the file by issuing the CLOSES macro call (see Section 
3.8). Continue other processing in the program, as desired. 


4, In anticipation of reopening the temporary file, restore the 
filename block to the FDB by accomplishing the reverse of 
step 2 above. 


5. Reopen the file by issuing any of the FCS macro calls that 
open existing files. Resume operations on the file; repeat 
the save, CLOSES, restore, open sequence any desired number 
of times. 


6. Before closing the file the last time, call the .MRKDL 
routine, as shown below, to mark the file for deletion: 


CALL »MRKDL 
The .MRKDL routine is described in Section 4.13.1. 
7. Close the file by issuing the CLOSES macro call. 


If the filename block is not saved, the file identification field 
therein is destroyed, since this field is reset to 0 when the file is 
closed. 


Thus, not saving the filename block before closing a temporary file 
results in a "lost" file, since no directory entry is made for a 
temporary file. The usual procedure of listing the volume's directory 
is therefore inapplicable. The only way such a file can be recovered 
is to use the File Structure Verification Utility program (VFY) to 
search the volume's index file. The VFY program has the capability to 
compare the files listed in all the directories on the volume with 
those listed in the index file. If a file appears in the index file, 
but not in a directory, VFY identifies that file for you. This 
program is described in detail in the IAS System Management Guide and 
RSX-11 Utilities Manual. = # 


3.4 OPNTSD - CREATE AND OPEN TEMPORARY FILE AND MARK FOR DELETION 


The OPNTSD macro call is issued to create and open a temporary file. 
This macro call is simply a convenient way to perform steps 1 and 6 
above. A file marked for deletion cannot be opened by another 
program. Furthermore, when the file is closed, it is automatically 
deleted from the volume, returning its space to the pool of available 
Storage on the volume for reallocation. 


The presumption in issuing the OPNTSD macro call is that the file thus 
created is to be used only once. This is a particularly desirable way 
to open a temporary file, since the file will be deleted even if the 
program terminates abnormally without closing the file. 


The OPNTSD macro call takes the same format and parameters as those of 
the generalized OPENSx macro call. 


NOTE 


If the OPNTSD macro call is issued for 
use with a temporary file containing 
sensitive information, it is recommended 
that you zero the file before closing 
it, or reformat the disk to destroy the 
sensitive information. (Although a 
temporary file is deleted after use, the 
information physically remains on the 
volume until written over with another 
file and could be analyzed by 
unauthorized users.) 


3.5 OFIDSX - OPEN FILE BY FILE ID 


The OFID$x macro call is issued to open an existing file using 
information stored in the file identification field (offset location 
N.FID) of the filename block in the FDB (not in your default filename 
block). Thus, issuing this macro call invokes an FCS routine that 
opens a file only by file ID (see Section 2.5). The OFIDSx call, 
which has the same format and takes the same parameters as those of 
the generalized OPENS$x macro call (see Section 3.1), is designed for 
use with overlaid programs. 


In describing the functions of the OFIDS$x macro call, either one of 
two assumptions may apply, as follows: 


1. That the necessary context for opening the file has been 
saved from a previous OPENSx operation and restored to the 
filename block in anticipation of opening that file by file 
ID. Saving and restoring the filename bDiock are discussed in 
detail in Section 2.5.1. 


2. That the desired file is to be opened for the first time. In 
that case, the necessary context for opening the file must 
first be stored in the file name block before the OFIDS macro 
call can be issued. 


In most cases, the latter assumption applies, requiring that the 
following procedures be performed: 


1. Call the .PARSE routine (see Section 4.7.1). This routine 
takes information from a specified dataset descriptor and/or 
default filename block, and initializes and fills in the 
specified filename block. 


2. Call the .FIND routine (see Section 4.8.1). This routine 
locates an appropriate directory entry for the file (by file 
name) and stores the file identification information found 
there in the 6-byte file identification field of the filename 
block, starting at offset location N.FID. As a result of 
Steps 1 and 2, the necessary context then exists in the 
associated filename block for opening the file by file ID. 


3. Issue the OFIDSx macro call. 
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The advantage in using the .PARSE and .FIND routines in conjunction 
with the OFIDSx macro call is that you can overlay the program, 
placing .PARSE and .FIND on one branch, and the code for OFIDSx on 
another branch. This overlay structure reduces the program's overall 
memory requirements. 


Unlike the other FCS macro calls for opening files, the OFIDS$x macro 
call requires a nonzero value in the first word of the file 
identification field (N.FID) in order to work properly. When this 
field contains a nonzero value, FCS assumes that the remaining context 
necessary for opening that file is present and, accordingly, opens the 
file by file ID. 


Opening an existing file by file ID for write access is a_ special 
case. Because it is intended to rewrite the existing file, the 
following occur: 


e Any initial allocation (F.CNTG) is ignored. 


e File access byte (F.FACC) value NA.NSP (do not supersede file) 
is ignored. 


e File access byte (F.F 
set even though th 
created. 


reate new file) is 
g rewritten rather than 


e This operation may not be performed on ANSI magnetic tape. 
The data in the file header labels is not changed when the 
file is written. See Section 5.2 for information on 
positioning file on tape to rewrite a file in a particular 
position. 


3.6 OFNBSX OPEN FILE BY FILENAME BLOCK 


The OFNBS$x macro call is issued to open either an existing file or to 
create and open a new file using file name information in the filename 
block. Similar to the OFIDSx macro call above, the OFNBSx call is 
designed for use with overlaid programs. However, the OFNBS$x macro 
call differs in two important respects: it can be issued to create a 
new file, and it can be issued to open a file by filename block. 


The OFNBSx call has the same format and takes the same parameters as 
those of the generalized OPENSx macro call (as described in Section 
3.1.1, as follows, 


OFNBSx fdb,lun,dspt,racc,urba,urbs,err 


The OFNBSx macro also uses the same suffixes that are available to the 
OPENSx macro: OFNBSR, OFNBSW, OFNBSM, OFNBSU, OFNBSA. The suffixes 
have the same meaning as they do for OPENSx (see Table 3-1). 


In describing the functions of the OFNBS$x macro call, the same 
assumptions outlined above for OFIDSx apply, namely, that the filename 
block has been saved and restored in anticipation of issuing the 
OFNBSx macro call, or that the file is being opened for the first 
time. Since the procedures for saving and restoring the filename 
block are detailed in Section 2.5.1, the following discussion assumes 
that the desired file is being opened for the first time. In this 
case, the filename block in the FDB must be initialized, as described 
below. 
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To open a file by filename block, the following information must be 
present in the filename block of the associated FDB: 


1. The file name (offset location N.FNAM) 
2. The file type or extension (offset location N.FTYP) 
3. The file version number (offset location N.FVER) 
4. The directory ID (offset location N.DID) 
5. The device name (offset location N.DVNM) 
6. The unit number (offset location N.UNIT) 
In providing the information above to the filename block, you can use 


either of two general procedures, as described in the following 
sections. 


3.6.1 Dataset Descriptor and/or Default Filename Block 


If the dataset descriptor contains all the required information listed 
above, perform the following procedures: 


a met? Lhe ra Cant A 7? #1.N 
Le Call the .PARSE routine {SSS BSscrvisn Seleije This 


4 
takes information from a specified dataset descriptor and/ 
default filename block and fills in the appropriate offse 
of a specified filename block. 


2. Issue the OFNBSx macro call. 


3.6.2 Default filename Block Only 


1 lename block is to be used in providing the required 
n to Pcs, pectorn the following procedures: 


1. Issue the NMBLKS macro call (see Section 2.4.2) to create and 
initialize a default filename block. With the exception of 
the directory ID, this structure provides all the requisite 
information to FCS. 


2. To provide the directory ID, call either of the following 
routines: 


a. Call the .GTDIR routine (see Section 4.9.1) to retrieve 
the directory ID from the specified dataset descriptor 
and to store the directory ID in the default file name 
block 


b. Call the .GTDID routine (see Section 4.9.2) to retrieve 
the default UIC from $$FSR2 and to store the directory ID 
in the default file name block. 


3. Move the entire default filename block manually into the 
filename block associated with the file being opened. 


4. Issue the OFNBSx macro call. 
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Note that the coding for OFNBSx operations normally resides in an 
overlay apart from that containing the other FCS routines identified 
above. 


Issuing the OFNB$x macro call is usually done under the premise that 
the filename block contains the requisite information, as described 
above. However, if the file identification field (offset location 
N.FID) in the filename block contains a nonzero value when the call to 
OFNBSx is issued, the file is unconditionally opened by file ID. 


If you expect to open both new and existing files, and memory 
conservation is an objective, the OFNB$x macro call is most suitable 
for opening such files. The OFIDSx coding should not be included in 
the same overlay with OFNBSx, since OFIDSx overlaps the function of 
OFNBSx and, therefore, needlessly consumes memory space. 


3.7 OPENS - GENERALIZED OPEN FOR SPECIFYING FILE ACCESS 


Usually, when you wish to create a file, the file name and the file 
type are specified, and FCS is allowed to assign the next higher file 
version number. However, if the OPENSW macro call is issued for a 
file having an explicit file name, file type, and file version number, 
and a file of that description already exists in the specified UFD, 
the old file is superseded. 


By issuing the OPENS macro call without an alphabetic suffix, and by 
specifying two additional parameters, you can inhibit the automatic 
superseding of a file when a duplicate file specification is 
encountered in the UFD. Rather than deleting the old version of the 
file, an error indication (IE.DUP) is returned to offset location 
F.ERR of the applicable FDB. 


All parameters of this macro call are identical to those specified for 
the generalized OPENSx macro call (see Section 3.1), with the 
exception of the facc parameter and the dfnb parameter. These 
additional parameters are described below. To open a file without 
superseding an existing file having an identical file specification, a 
macro call of the following form is used: 


OPENS fdb,facc,lun,dspt,dfnb,racc,urba,urbs,err 
facc 


Any one or an appropriate combination of the following symbolic 
values indicating how the specified file is to be accessed: 


e FO.RD - Indicates that an existing file is to be opened for 
reading only 


e FO.WRT - Indicates that a new file is to be created and 
opened for writing 


e FO.APD - Indicates that an existing file is to be opened 
and appended 


e FO.MFY - Indicates that an existing file is to be opened 
and modified 


e FO.UPD - Indicates that an existing file is to be opened, 
updated, and, if necessary, extended 
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e FA.NSP - Indicates, in combination with FO.WRT above, that 
the old file having the same file specification is not to 
be superseded by the new file 


e FA.TMP - Indicates, in combination with FO.WRT above, that 
the file is to be a temporary file 


e FA.SHR - Indicates that the file is to be opened for shared 
access 


dfnb 


The symbolic address of the default filename block. This 
parameter is the same as that described in connection with the 
FDOPSA/FDOPSR macro call. 


The above parameters initialize FDB offset locations F.FACC and F.DFNB 
with appropriate values. 


Any logically consistent combination of the above file access symbols 

is permissible. The particular combination required to create and 

write a new file without superseding an existing file is shown below: 
OPENS #OUTFDB,#FO.WRT! FA.NSP 


The following macro call creates a temporary file for shared access: 


OPENS #OUTFDB, #FO.WRT! FA. TMP! FA.SHR 


NOTE 


You can use RO only to pass the _ FDB 
address parameter. Any other use of RO 
when you issue the OPENS macro call will 
fail. 


3.8 CLOSES - CLOSE SPECIFIED FILE 

When the processing of a file is completed, you must close it by 
issuing the CLOSES macro call. The CLOSES operation performs the 
following housekeeping functions: 


1. Waits for all I/O operations in progress for the file to be 
completed (multiple-buffered record I/O only) 


2. Ensures that the FSR block buffer, which contains data for an 
output file, is completely written if it is partially filled 
(record I/O only) 

3. Deaccesses the file 


4. Releases the FSR block buffer(s) allocated for the file 
(record I/0 only) 


5. Prepares the FDB for subsequent use by clearing appropriate 
FDB offset locations 


6. Calls an optional user-coded, error-handling routine if an 
error condition is detected during the CLOSES operation 


3-18 


FILE-PROCESSING MACRO CALLS 


Note that I/O does occur in items 1 and 2 above. Therefore, your 
program should include error processing for CLOSES calls as it would 
for calls to PUTS. 


Issuing a CLOSES when a file is already closed resuits in a success 
status code. Closing a file that is already closed is not an error. 


3.8.1 Format of CLOSE$ Macro Call 
The CLOSES macro call takes the following format: 
CLOSES fdb,err 
fdb 
A symbolic value of the address of the associated FDB. 
err 


The symbolic address of an optional user-coded, error-handling 
routine. 


The following examples illustrate the use of the CLOSES macro call: 
CLOSES #FDBIN,CLSERR 
CLOSES ,CLSERR 
CLOSES RO 


The first example shows an explicit declaration for the relevant FDB, 
and the symbolic address of an error-handling routine to be entered if 
the CLOSES operation is not completed successfully. The last two 
examples assume that RO currently contains the address of the 
appropriate FDB. 


3.9 GETS - READ LOGICAL RECORD 


The GETS macro call is used to read logical records from a file. 
After a GETS operation, the next record buffer descriptors in the FDB 
always identify the record just read; that is, offset location 
F.NRBD+2 contains the address of the record just read, and offset 
location F.NRBD contains the size of that record (in bytes). This is 
true of GETS operations in both move and locate mode. 


In move mode, a GETS operation moves a record to your record buffer 
(as defined by the current contents of F.URBD+2 and F.URBD), and the 
address and size of that record are then returned to the next’ record 
buffer descriptors in the FDB (F.NRBD+2 and F.NRBD). 


In locate mode, if the entire record resides within the FSR block 
buffer, then the address and the size of the record just read are 
returned to the next record buffer descriptors (F.NRBD+2 and F.NRBD). 
If, on the other hand, the entire record does not reside within the 
FSR block buffer, then that record is moved piecemeal into your record 
buffer, and the address of your record buffer and the size of the 
record are returned to offset locations F.NRBD+2 and F.NRBD, 
respectively. 
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After returning from a GETS$ operation in locate mode, regardless of 
whether moving the record was necessary, F.NRBD+2 always contains the 
address of the record just read, and F.NRBD always contains the _ size 
of that record. 


If the record read was a sequenced record, the sequence number is 
stored in F.SEQN regardless of whether the GETS was in move mode or 
locate mode. 


GETS$ operations are fully synchronous; that is, record I/O operations 
are completed before control is returned to your program. 


Specific FDB requirements for GETS$ operations are presented in Section 
3.9.2 below. 


3.9.1 Format of GETS Macro Call 


To read a logical record, the GET$ macro call is specified in the 
following format: 


GETS fdb,urba,urbs,err 

fdb 
A symbolic value of the address of the associated FDB. 

urba 
The symbolic address of your record buffer to be used for’ record 
I/O operations in move or locate mode. When specified, this 
parameter initializes FDB offset location F.URBD+2. 

urbs 
A numeric value defining the size (in bytes) of your’ record 
buffer. This parameter determines the largest record that can he 
placed in your record buffer in move or locate mode. When 
specified, this parameter initializes offset location F.URBD in 
the associated FDB. 

err 


The symbolic address of an optional user-coded, error-handling 
routine. 


If neither the urba nor the urbs parameter is specified in the GETS 
macro call, FCS assumes that these requisite values have been supplied 
previously through the FDRCSA, the FDRCSR, or the generalized OPENSx 
macro call. Any resulting nonzero values in offset locations F.URBD+2 
and F.URBD are used as the address and the length, respectively, of 
your record buffer. 


If either of the following conditions occurs during record I/0 
operations, FCS returns an error indication (IE.RBG) to offset 
location F.ERR of the FDB, indicating an illegal record size: 


1. In move mode, the record size exceeds the limit specified in 
offset location F.URBD. 
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2. In locate mode, the record size exceeds the limit specified 
in offset location F.URBD, and the record must be moved 
because it crosses block boundaries. 

In both move and locate mode, only data up to the amount specified in 
F.URBD is placed in your buffer. The next GETS begins reading at the 
beginning of the next record. 

The following statements represent the use of the GETS macro call: 

GETS RO,,,ERROR 

GETS ,#RECBUF,#25.,ERROR 

GETS #INFDB 


In the first example, the address of the desired FDB is assumed to be 


present in RO. Note that the next two parameters, that is, your 
record buffer address (urba) and your record buffer size (urbs), are 
null. In this case, FCS assumes that the appropriate values for FDB 


offset locations F.URBD+2 and F.URBD, respectively, have been 
specified previously in the FDRCSA, the FDRCSR, or the generalized 
OPENSx macro call. The final parameter in the string is the symbolic 
address of a user-coded, error-handling routine. 


The second example also assumes that RO contains the address of the 
desired FDB. Explicit parameters then define the address and the 
Size, respectively, of your record buffer and a user-coded error 
handler. 


The last example shows a GET$ macro call in which only the address of 
the FDB is specified. 


NOTE 


You can use RO only to pass the _ FDB 
address. Any other use of RO when you 
issue the GETS macro will fail. 


3.9.2 FDB Mechanics Relevant to GETS Operations 


The following sections summarize the essential aspects of GETS 
operations in move and locate mode with respect to the associated FDB. 


The discussions below focus mainly on whether your record buffer is 
required under certain conditions. In this regard, you should recall 
that your record buffer descriptors, that is, the urba and the urbs 
parameters, may be specified in the FDRCSA, the FDRCSR, or the 
generalized OPENSx macro call, as well as the I/0O-initiating GETS 
macro call. These parameters need be present in the GETS macro call 
(to appropriately initialize the FDB) only if not previously supplied 
through some other available means. 


If operating in random access mode, the number of the record to be 
read is maintained by FCS in offset locations F.RCNM and F.RCNM+2 of 
the associated FDB. FCS increments this value after each GETS or 
GETSR operation to point to the next record in the FSR block buffer. 


Thus, unless your program alters the values in locations F.RCNM and 
F.RCNM+2 before each issuance of the GETS or GETSR macro call, the 
next record in sequence is read. Your specified record buffer size 
(that is, the urbs parameter) always determines the largest record 
that can be read during a GETS operation. 


3.9.2.1 GETS Operations in Move Mode - With respect to GETS 
operations in move mode (refer to Section 2.2 for information on move 
mode), the following generalization applies. If records are always 
moved to the same user record buffer, the urba and urbs parameters 
need be specified only in the initial GET$ macro call. Alternatively, 
these values may be specified beforehand through any available means 
identified above for initializing the user record buffer descriptor 
cells in the FDB. In any case, offset locations F.URBD+2 and F.URBD 
remain appropriately initialized for all subsequent GETS operations in 
move mode that involve the same user record buffer. 


3.9.2.2 GETS Operations in Locate Mode - In performing GETS 
Operations in locate (refer to Section 2.2 for information on locate 
mode) mode, you should take into account the following: 


NOTE 


In the following discussion, reference 
is made to the FSR block buffer. By 
default, the blocksize that FCS uses is 
equivalent to the buffer size of the 
device on which the file is opened. LE 
big buffering is enabled (that is, an 
ovbs parameter value is specified in the 
FDBFSx macro call as described in 
Section 2.2.1.6), the FSR block buffer 
will be more than one biock iong. As a 
result, it may not be necessary to move 
a record even though it crosses block 
boundaries, since both blocks are 
currently within the FSR block buffer 
space. Thus, moves are only necessary 
when the record crosses a buffer 
boundary, which is not necessarily the 
same as a biock boundary in a 
big-buffered file. 


e If fixed-length records are to be processed, and if they fit 
evenly within the FSR block buffer, your record buffer 
descriptors need not be present in the associated FDB. 


e If fixed-length records that do not fit evenly within the FSR 
block buffer are to be processed, or if variable-length 
records are to be processed, your record buffer descriptors 
need not be present in the FDB, provided that the file being 
Processed exhibits the attribute of records not being allowed 
to cross block boundaries (FD.BLK). 
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The property of records not crossing block boundaries is 
established as the file is created. Specifically, if offset 
location F.RATT in the FDB is initialized with FD.BLK prior to 
file-create time, then the records in the resulting file are 
not allowed to cross buffer boundaries. 


For an existing file, your file attribute section of the file 
header block is read when the file is opened; thus, all 
attributes of that file are made known to FCS, including 
whether records within that file are allowed to cross block 
boundaries. 


The design of FCS requires you to utilize your record buffer 
only in the event that records (either fixed or variable in 
length) cross buffer boundaries. 


e If a GETS operation is performed in locate mode, and the 
record is contained entirely within the FSR block buffer, the 
address of the record within the FSR block buffer and the size 
of that record are returned to offset locations F.NRBD+2 and 
F.NRBD, respectively, in the associated FDB. However, if that 
record crosses buffer boundaries, it is moved to your record 
buffer. In this case, the address of your record buffer and 
the size of the record are returned to offset locations 
F.NRBD+2 and F.NRBD, respectively. 


In summary, if the potential exists for crossing buffer boundaries 
during GETS operations in locate mode, then the your record buffer 
descriptors must be supplied through ny available means to 
appropriately initialize offset locations F.URBD+2 and F.URBD in the 
associated FDB. 


3.10 GETSR - READ LOGICAL RECORD IN RANDOM MODE 


The GETSR macro call is used to read fixed-length records from a_ file 
in random mode. Thus, by definition, issuing this macro call requires 
that you be intimately familiar with the structure of the file to be 
read and, furthermore, that you be able to specify precisely the 
number of the record to be read. 


The GETS and GETSR macro calls are identical, except that the 
parameter list of GETSR includes the specification of the desired 
record number. If the desired record number is already present in the 
FDB (at offset locations F.RCNM and F.RCNM+2), then GETS may be used. 
If, however, the record access byte in the FDB (offset location 
F.RACC) has not been initialized for random access operations with 
FD.RAN in the FDRCSA, the FDRCSR, or the generalized OPENSx macro 
call, then neither GET$ nor GETSR will read the desired record. 


The GETSR macro call takes two more parameters in addition to those 
specified in the GETS macro call, as shown below: 


GETSR fdb,urba,urbs,lrcenm,hrcnm,err 


lrcnm 


A numeric value specifying the low-order 16 bits of the number of 
the record to be read. This value, which must be specified, is 
stored in offset location F.RCNM+2 in the FDB. The GETSR macro 
call seldom requires more than 16 bits to express the record 
number. A logical record number up to 65,536(decimal) may be 
specified through this parameter. If this parameter is not 
sufficient to completely express the magnitude of the _ record 
number, the following parameter must also be specified. 


hrenm . 


A numeric value specifying the high-order 15 bits of the number 
of the record to be read. This value is stored in FDB offset 
location F.RCNM. If specified, the combination of this parameter 
and the Ilrcnm parameter above determines the number of the 
desired record. Thus, an unsigned value having a total of 31 
bits of magnitude may be used in defining the record number. 


If this parameter is not specified, offset location F.RCNM 
retains its initialized value of 0. 


If F.RCNM is used to express a deSired record number for any 
given GETSR operation, this cell must be cleared before issuing a 
subsequent GETS$R macro call that requires 16 bits or less to 
express the desired record number; otherwise, any residual value 
in F.RCNM yields an incorrect record number. 


If the Ilrcnm and hrcnm parameters are not specified in a subsequent 
GETSR macro call, the next sequential record is read since the record 
number in offset locations F.RCNM+2 and F.RCNM is automatically 
incremented with each GETS operation. In the case of the first GETSR 
after opening the file, record number 1 is read, because the record 
number has been initialized to 0 by the OPEN. If a record other than 
the next sequential record is to be read, you must explicitly specify 
the number of the desired record. 


The following statements represent the use of the GETSR macro call: 
GETSR #INFDB, #RECBUF, #160. ,#1040.,,ERROR ’ 
GETSR #FDBADR, #RECBUF, #160. ,R3 


Note in the first example that the number of the desired record to be 
read, that is, 1040(decimal), is expressed through the first of two 
available fields for this purpose; the second field is not required 
and is therefore reflected as a null specification. 


The second example reflects the use of general register 3 in 
specifying the logical record number. This register, or any other 
location so used, must be preset with the desired record number before 
issuing the GETSR macro call. 


NOTE 


RO can only be used to pass the _ FDB 
address parameter. Any other use of RO 
when issuing the GETS$R macro call will 
fail. 
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3.11 GET$S - READ LOGICAL RECORD IN SEQUENTIAL MODE 


The GETSS macro call is used to read logical records from a file in 
sequential mode. Although the routine invoked by the GETSS macro call 
requires less memory than that invoked by GETS (see Section 3.9), 
GETSS has the same format and takes the same parameters. The GETSS 
macro call is designed specifically for use in an overlaid environment 
in which the amount of memory available to the program is limited and 
files are to be read in strictly sequential mode. 


If both GETSS and PUTSS are to be used by the program, note that the 
savings in memory utilization over GETS and PUTS can be realized only 
if GETSS and PUTSS are placed on different branches of the overlay 
structure. 


3.12 PUTS - WRITE LOGICAL RECORD 


The PUTS macro call is used to write logical records to a file. Te 
operating in random access mode, the number of the record to be 
written is maintained by FCS in offset locations F.RCNM and F.RCNM+2 
of the associated FDB. FCS increments this value after each PUTS or 
PUTSR operation to point to the next sequential record position. 
Thus, unless your program alters this value before issuing another 
PUTS or PUTSR operation, the next record in sequence is written. 


For PUTS operations, offset locations F.NRBD+2 and F.NRBD in the 
associated FDB must contain the address and the size, respectively, of 
the record to be written. The distinction between move mode and 
locate mode for PUTS operations relates to the building or the 
assembling of the data into a record. Specifically, in move mode the 
record is built in a buffer of your choice. This buffer is not 
necessarily your record buffer previously described in the context of 
record I/0 operations. In other words, you can build records in an 
emeea of a program apart from that normally defined by your’ record 
buffer descriptors in the FDB (F.URBD+2 and F.URBD). In this case, 
the address of the record buffer so used and the size of the _ record 
are specified in the PUTS macro call, and the record thus built is 
then moved into the FSR block buffer. 


In locate mode, however, the record is built at the address specified 
by the contents of offset location F.NRBD+2, and only the record size 
need be specified in the PUTS macro call. Then, if the record. so 
built is not already in the FSR block buffer, it is moved there as the 
PUTS operation is performed. 


If the records in the file are sequenced records, the field F.SEQN in 
the FDB contains the sequence value, which you can modify. 


PUTS operations are fully synchronous; that is, record I/O operations 
are completed before control is returned to the user program. 


A random PUTS operation in locate mode requires the use of the .POSRC 
routine. This operation is described in detail in Section 4.9.2. 
Specific FDB requirements for PUTS operations are presented in Section 
3.12.2 below. 
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3.12.1 Format of PUT$ Macro Call 
The PUTS macro call takes the following format: 
PUTS fdb,nrba,nrbs,err 
fdb 
A symbolic value of the address of the associated FDB. 
nrba 
The symbolic address of the next record buffer, that is, the 


address of the record to be PUTS. This parameter initializes FDB 
offset location F.NRBD+2. 


nrbs 
A numeric value specifying the size of the next record buffer, 
that is, the length of the record to be PUTS. This parameter 
initializes FDB offset location F.NRBD. 

err 


The symbolic address of an optional user-coded, error-handling 
routine. 


The following examples represent the uses of the PUTS macro call: 


PUTS #FDBADR, , ,ERRRT 
PUTS 7,#160. ,ERRRT 
PUTS RO 


In the first example, note that the next record buffer address (nrba 
parameter) and the next record buffer size (nrbs parameter) are null. 
These null specifications imply that the current values in offset 
locations F.NRBD+2 and F.NRBD of the associated FDB are suitable to 
the current operation. Note also that fixed-length records could also 


be written in locate mode by issuing this macro call. 


The second example contains null specifications in the first two 
paramet+: fields, assuming that RO currently contains the address of 
the assoc‘ated FDB and that variable-length records are to be written 
to the file. 


The last example specifies only the address of the  FDB; all other 
parameter fields are null. 


NOTE 


RO can only be used to pass the FDB 
address parameter as shown in the above 
example; it cannot be used to pass any 
other parameter in the PUTS macro call. 
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3.12.2 FDB Mechanics Relevant to PUTS Operations 


The discussions below highlight aspects of PUTS operations in move and 
locate mode that have a bearing on the associated FDB. 


The conditions under which your record buffer is or is not used are 
summarized. As is the case for GET$ operations, if your record buffer 
is required for PUTS operations, the buffer descriptors (that is, the 
urba and urbs parameters) may be supplied to the associated FDB 
through the FDRCSA, the FDRCSR, or the generalized OPENSx macro call. 
In any case, offset locations F.URBD+2 and F.URBD must be 
appropriately initialized if PUTS operations require the utilization 
of your record buffer. Note, however, that PUTS operations in move 
mode never require a record buffer. 


If your record buffer is required, the specified size of that buffer 
(that is, the urbsS parameter) always determines the size of the 
largest record that can be written to the specified file. 


Whether in move or locate mode, a PUTS operation uses the information 
in offset locations F.NRBD+2 and F.NRBD, that is, the next record 
buffer descriptors, to determine whether the record must be moved into 
the FSR block buffer. In the event that the record does have to be 
moved, and the size of that record is such that it cannot fit in the 
Space remaining in the FSR block buffer, one of two possible 
operations is performed: 


1. If records are allowed to cross block boundaries, then the 
first part of the record is moved into the FSR block buffer, 
thereby completing a virtual block. That block buffer is 
then written out to the volume, and the remaining portion of 
the record is moved into the beginning of the next FSR block 
buffer. 


2. If records are not allowed to cross block boundaries (because 
of the file attribute FD.BLK specified in the associated 
FDB), then the FSR block buffer is written out to the volume 
as is, and the entire record is moved into the beginning of 
the next FSR block buffer. 


3.12.2.1 PUT$ Operations in Move Mode - A PUTS operation in move mode 
(see Section 2.2) is basically driven by specifying in each PUTS macro 
call the address and the size of the record to be written. Then, as 
the PUTS operation is performed, FCS moves the _ record into the 
appropriate area of the FSR block buffer. 


In summary, the following generalizations apply for PUTS operations in 
move mode: 


1. Your record buffer descriptors need not be present in the FDB 
because the programmer is dynamically specifying the address 
and the length of the record to be written at each issuance 
of a PUTS macro call. The values so specified dynamically 
update offset locations F.NRBD+2 and F.NRBD in the associated 
FDB. 


2. If the file consists of fixed-length records, then the 
generalized OPENS$x macro call (see Section 3.1) initializes 
offset location F.NRBD with the appropriate record size, as 
defined by the contents of offset location F.RSIZ. Thus, the 
size of the record need not be specified as the nrbs 
parameter in any PUTS macro call involving this file. 
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3. If variable-length records are being PUTS, the size of each 
record must be specified as the nrbs parameter in each PUTS 
macro call involving this file, thus setting offset location 
F.NRBD to the appropriate record size. 


3.12.2.2 PUTS Operations in Locate Mode - Basically, your record 
buffer is required for PUTS operations in locate mode (see Section 
2.2) only when the potential exists for records to cross’ buffer 
boundaries. In other words, if there is insufficient space in the FSR 
block buffer to accommodate the building of the next record, you must 
provide a buffer in your memory space in order to build that record. 


When a file is initially opened for PUTS operations in locate mode, 
FCS sets up offset location F.NRBD+2 to point to the area in the FSR 
block buffer where the next record is to be built. Then, each PUTS 
operation thereafter in locate mode updates the address value in this 
cell to point to the area in the’ FSR block buffer where the next 


record is to be built. Thus, after each PUTS operation in locate 
mode, F.NRBD+2 points to the area where the next record is to be 
built. This logic dictates whether your record buffer is required in 


locate mode. 


In this regard, the following generalizations apply: 


NOTE 


In the following discussion, reference 
is made to the FSR block buffer. By 
default, the block size that FCS uses is 


ecuivelent..te the .buifter size or. che 
device on which the file is opened. Tf 


big buffering is enabled (that is, an 
ovbs parameter value is specified in the 
FDBFSx macro call, as described in 
Section 2.2.1.6) the FSR block buffer 
will be more than one block long. As a 
result, it may not be necessary to move 
a record even though it crosses block 
boundaries, since both blocks are 
currently within the FSR block buffer 
Space. Thus, moves are only necessary 
when the record crosses a buffer 
boundary, which is not necessarily the 
same as a block boundary in a 
big-buffered file. 


1. If fixed-length records are being PUTS and they fit evenly 
within the FSR block buffer, your record buffer is not 
required. 


2. If a fixed-length record crosses block boundaries, your 
record buffer descriptors must be present in offset locations 
F.URBD+2 and F.URBD of the associated FDB. In this case, 
after determining that the record cannot fit in the FSR block 
buffer, FCS sets offset location F.NRBD+2 to point to your 
record buffer. Then, when the record is PUTS, it is moved 
from your record buffer to the FSR block buffer. 


3. If a variable-length record is being PUTS, the potential 
exists for crossing block boundaries. In this case, your 
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record buffer descriptors must be present in offset locations 
F.URBD+2 and F.URBD of the associated FDB. Moreover, the 
size of each variable-length record must be specified as’ the 
nrbs parameter in each PUTS macro call. 


Determining if FCS points offset location F.NRBD+2 to the FSR 
block buffer for the PUTS operation or to your record buffer 
is based on whether there is potentially enough room in the 
FSR block buffer to accommodate the record. 


Because the records are variable in length, it must be 
assumed that the largest possible record is PUTS, as defined 
by the size of your record buffer (F.URBD). Thus, if a 
record of this defined size cannot fit in the space remaining 
in the FSR block buffer, FCS sets offset location F.NRBD+2 to 
point to your record buffer. 


Each PUTS operation in locate mode sets up the FDB for the next PUTS. 
In other words, the specified record size is used by FCS as the 
worst-case condition in determining whether sufficient space exists in 
the FSR to build the next record. 


If variable-length records are being processed that are shorter’ than 
the largest defined record size, FCS may move records unnecessarily 
from your record buffer to the FSR block buffer. For example, assume 
that you have allocated a 132-byte record buffer. Assume further that 
the available remaining space in the FSR block buffer is less than 132 
bytes. In this case, FCS continues to point to your record buffer for 
PUTS operations, even if you continue to PUTS short (10- or 20-byte) 
records. Thus, some unavoidable movement of records takes place in 
locate mode. 


If the largest record that you intend to PUTS is 80 bytes, for 
example, then the largest defined record size should not be specified 
as 132 bytes (or any length larger than that intended to be PUTS). 
Aside from having to allocate a smaller user record buffer, PUTS 
operations in locate mode are more efficient if this precaution is 
observed. Exercising care in this regard reduces the tendency to move 
records from your record buffer to the FSR block buffer when they 
might otherwise be built directly in the FSR block buffer. 


3.13  PUTSR - WRITE LOGICAL RECORD IN RANDOM MODE 


The PUTSR macro call is used to write fixed-length records to a file 
in random mode. As noted in Section 3.10 in connection with the GETSR 
macro call, operations in random access mode require you to be 
intimately familiar with the contents of such files. The PUTSR macro 
call also relies entirely on you to specify the number of the record 
before a specified PUTS operation can be performed. Since the usual 
purpose of a PUTSR operation is to update known records in a file, it 
is assumed that you also know the number of such records within the 
file. 


The PUTS and PUTSR macro calls are identical, except that PUTSR allows 
the specification of the desired record number. If the desired record 
number is already present in the FDB (at offset locations F.RCNM and 
F.RCNM+2), then PUTS and PUTSR may be used interchangeably. However, 
if the record access byte in the FDB (offset location F.RACC) has not 
been initialized for random access operations with FD.RAN in the 
FDRCSA, the FDRCSR, or the generalized OPENSx macro call, then neither 
PUTS nor PUTSR will write the desired record. 
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The PUTSR macro call takes two more parameters in addition to those 
specified in the PUTS macro call, as shown below: 


PUTSR fdb,nrba,nrbs,lrcnm,hrcnm,err 
lrcnm 


A numeric value specifying the low-order 16 bits of the number of 
the record to be processed. This parameter serves the same 
purpose as the corresponding parameter in the GETSR macro call 
(see Section 3.10), except that it identifies the record to be 
written. 


hrcnm 


A numeric value specifying the high-order 15 bits of the number 
of the record to be processed. ThisS parameter serves the same 
purpose as the corresponding parameter in the GETSR macro call, 
except that it identifies the record to be written. 


If this parameter is not specified, offset location F.RCNM 
retains its initialized value of 0. 


If F.RCNM is used in expressing a desired record number for any 
given PUTSR operation, you must clear this cell before issuing a 
subseauent PUTSR macro eall that roeaui re 4 bits Or Less in 


wasn & eyuae es iv 
expressing the desired record number; otherwise, any residual 
value in F.RCNM results in an incorrect record number. 


The Ircnm and hrenm parameters initialize offset locations F.RCNM+2 
and F.RCNM, respectively, in the associated FDB. If these values are 
not specified in a subsequent PUTSR macro call, the next sequential 
record is written, since FCS automatically increments the record 
number in these cells after each PUTS operation. In the case of the 
first PUTSR after opening the file, record number 1 is written. Note 
that this is true even if the file has been opened for an append 
(OPENSA). If a record other than the next Sequential record is to be 


written, you must explicitly specify the number of the desired record. 


NOTE 


A random mode PUTS operation executed in 
locate mode must be preceded by a call 
to .POSRC. Since locate mode allows you 
to store data directly into the block 
buffer, the file must be positioned so 
that the desired record position is in 
fact in the block buffer. See Section 
4.10.2 for further details. 


Examples of the use of the PUTSR macro call follow: 

PUTSR #OUTFDB, #RECBUF, , #12040.,,ERRLOC 

PUTSR #FDBADR, #RECBUF, ,R4 

PUTSR #FDBADR, #RECBUF, , LRN 
In the first example, the presence of RECBUF as the next record buffer 
address (nrba) parameter merely indicates that you are specifying the 


address of the record. Although specifying this address repeatedly is 
unnecessary, it is not invalid. Normally, a buffer address is 
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specified dynamically, since other PUTS macro calls may be referencing 
different areas in memory; thus, the address of the record must be 
explicitly specified in each PUTS macro call. Note also that the next 
record buffer size (nrbs) parameter is null, since this parameter is 
required only in the case of writing variable-length records. Also, 
the second of the two available parameters for defining the record 
number is null. 


Note in the second and third examples that R4 and a memory location 
(LRN) are used to specify the logical record number. Such a 
specification assumes that you have preset the desired record number 
in the referenced location. 


NOTE 


You can use RO only to pass the _ FDB 
address. Any other use of RO when you 
issue the PUTSR macro call will fail. 


3.14 PUTS$S - WRITE LOGICAL RECORD IN SEQUENTIAL MODE 


The PUTSS macro call is used to write logical records to a file in 
sequential mode. Although the routine invoked by the PUTSS macro call 
requires less memory than that invoked by PUTS (see Section 3.12), 
PUTSS has the same format and takes the same parameters. The PUTSS 
macro call is designed specifically for use in an overlaid environment 
in which the amount of memory available to the program is limited and 
files are to be written in strictly sequential mode. 


If both GETSS and PUTSS are to be used by the program, the savings in 
memory utilization over GETS and PUTS are realized only if GETSS and 
PUTSS are placed on different branches of the overlay structure. 


3.15 READ$ - READ VIRTUAL BLOCK 


The READS macro call is issued to read a virtual block of data from a 
block-oriented device (for example, a magtape, a disk, or DECtape). 
In addition, if certain optional parameters are specified in the READS 
macro call, status information is returned to the I/O status block 
(see Section 2.8.2), and/or the program traps to a user-coded AST 
service routine at the completion of block I/0 operations (see Section 
2,803) 


In issuing the READS (or WRITES) macro call, you are responsible for 
synchronizing all block I/O operations. For this reason, the WAITS 
macro call is provided (see Section 3.17), allowing you to suspend 
program execution until a specified READS/WRITES operation has been 
completed. It is important, however, that you test the contents of 
F.ERR in the FDB for error codes immediately after issuing the 
READS/WRITES call as well as on return from the WAITS call. When 
errors occur during multiple-block transfers, the second word of the 
I/O status block will contain the number of bytes transferred before 
the error occurred. The READS/WRITE operations can return error codes 
distinct from those that can be present on completing a WAITS 
operation. For example, IE.EOF will be returned upon completing the 
READS operation, but not upon completing WAITS. 
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When the WAITS macro call is issued in conjunction with a READS (or 
WRITES) macro call, you must ensure that the event flag number and the 
I/O status block address specified in both macro calls are the same. 


When the WTSES$ macro call is issued to wait for I/0 completion, the 
issuing task must check I/O errors by examining the I/O status block 
(defined by the task). (The I/O status block is described in Section 


2.8.2.) When WTSES is used, FCS will not return a completion code to 
offset F.ERR in the FDB. 


3.15.1 Format of READS Macro Call 


From the format below, note that the parameters of the READS macro 
call are identical to those of the FDBKSA or the FDBKSR macro call, 
with the exception of the fdb and err parameters. Certain FDB 
parameters may be set at assembly time (FDBKSA), initialized at run 
time (FDBKSR), or set dynamically by the READS macro call. In any 
case, certain information must be present in the FDB before the 
specified READS (or WRITES) operation can be performed. These 
requirements are noted in Section 3.15.2 below. 


The READS macro call takes the following format: 


READS fdb,bkda,bkds,bkvb,bkef,bkst,bkdn,err 


fdb 
A symbolic value of the address of the associated FDB. 

bkda 
The symbolic address of the biock I/O buffer in your’ program. 
This parameter need not be specified if offset location F.BKDS+2 
has been previously initialized through either the FDBKSA or the 
FDBK$R macro call. 

bkds 
A numeric value specifying the size (in bytes) of the virtual 
block to be read. This parameter need not be specified if offset 
location F.BKDS has been previously initialized through either 
the FDBKSA or the FDBKSR macro call. In any case, the maximum 
block size that may be specified for file-structured devices is 
32256 bytes. 

bkvb 


The symbolic address of a 2-word block in your program containing 
the number of the virtual block to be read. This parameter 
causes offset locations F.BKVB and F.BKVB+2 to be initialized 
with the virtual block number; F.BKVB+2 contains the low-order 
16 bits of the virtual block number, and F.BKVB contains’ the 
high-order 15 bits. 


As noted in connection with the FDBKSA macro call described in 
Section 2.2.1.4, assembly-time initialization of the virtual 
block number in the FDB is ineffective, since the generalized 
OPENSx macro call sets the virtual block number in the FDB to l. 


bkef 


bkst 


bkdn 
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The virtual block number can be made available to FCS only 
through the FDBKSR macro call or the I/O-initiating READS (or 
WRITES) macro call after the file has been opened. The virtual 
block number is created as described in item 4 of Section 
22e Axl 


The READS function checks the specified virtual block number _ to 
ensure that it does not reference a nonexistent block, that is, a 
block beyond the end of the file. If the virtual block number 
references nonexistent data, an end-of-file (IE.EOF) error 
indication is returned to offset location F.ERR of the associated 
FDB; otherwise, the READS operation proceeds normally. If the 
total number of bytes goes beyond the end of the file, then as 
many blocks as exist are read and the byte count of the shortened 
transfer is returned in I/O STATUS+2. No error condition occurs, 
so you must check the count on each READ. An end-of-file 
indication is returned only if no blocks can be read. 


If the virtual block number is not specified through any of the 
available means identified above, automatic sequential operation 
results by default, beginning with virtual block number 1. The 
virtual block number is automatically incremented by the number 
of blocks read after each READS operation is performed. 


A numeric value specifying the event flag number to be used _ for 
synchronizing block I/0 operations. This event flag number is 
used by FCS to signal the completion of the specified block I/0 
operation. The event flag number, which may also be specified 
in either the FDBKSA or the FDBKSR macro call, initializes FDB 
offset location F.BKEF; if so specified, this parameter need not 


be included in the READS (or WRITES) macro call. 


If this optional parameter is not specified through any available 
means, event flag 32(decimal) is used by default. The function 
of an event flag is discussed in further detail in Section 2.8.1. 


The symbolic address of the I/O status block in the user. program 
(see Section 2.8.2). This parameter, which initializes offset 
location F.BKST, is optional. The I/O status block is filled in 
by the system when the requested block I/O transfer is completed, 
indicating the success/failure of the requested operation. 


The address of the I/O status block may also be specified in 
either the FDBKSA or the FDBKSR macro call. If the address of 
this 2-word structure is not supplied to FCS through any of the 
available means, status information cannot be returned to your 
program. Regardless, the event flag specified through the bkef 
parameter above is set to indicate block I/O completion, but, 
without an I/O status block, your program must assume that the 
operation (for example, READS or WRITES) was successful. 


The symbolic entry point address of an AST service routine (see 
Section 2.8.3). If this parameter is specified, a trap occurs 
upon completion of the specified READS (or WRITES) operation. 
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This parameter, which is optional, initializes offset location 
F.BKDN. This address value may also be made available to FCS 
through either the FDBKSA or the FDBKSR macro call, and, if so 
specified, need not be present in the READS (or WRITES) macro 
call. 


If the address of an AST service routine is not specified through 
any available means, no AST trap occurs at the completion of 
block I/O operations. 


err 


The symbolic address of an optional user-coded, error-handling 
routine. 


The following examples represent READS macro calls that may be issued 
to accomplish a variety of operations: 


READS RO 

READS #INFDB, 77477 2RRLOC 

READS RO,#INBUF,#BUFSIZ,,#22.,#IOSADR, #ASTADR, ERRLOC 
READS #INFDB, #INBUF, #BUFSIZ,#VBNADR 


The first example assumes that RU contains the address of the 
associated FDB. Also, all other required FDB initialization has been 
accomplished through either the FDBKSA or the FDBKSR macro call. 


The second example shows an explicit declaration of the associate FDB 
and includes the symbolic address of a uSer-coded, error-handling 
routine. 


In the third example, RO again contains the address of the associated 
FDB. The block buffer address and the size of the block are specified 
next in symbolic form. The address of the 2-word block in your 
program containing the virtual biock number is not specified, as 
indicated by the additional comma in the parameter string. The event 
flag number, the address of the I/O status block, and the address of 
the AST service routine then follow in order. Finally, the symbolic 


address of an optional error routine is specified. 


The fourth example reflects, as the last parameter in the string, the 
symbolic address of the 2-word block in your program containing the 
virtual block number. 


NOTE 


You can use RO only to pass the _ FDB 
address. Any other use of RO when you 
issue the READS macro call will fail. 
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3.15.2 FDB Requirements for READS Macro Call 


The READS macro call requires that the associated FDB be initialized 
with certain values before it can be issued. You can specify these 
values through either the FDBKSA or the FDBKSR macro calli, or they may 
be made available to the FDB through the various parameters of the 
READS macro call. In any case, the following values must be present 
in the FDB to enable READS operations to be performed: 


1. The block buffer address (in offset location F.BKDS+2) 
2. The block byte count (in offset location F.BKDS) 


3. The virtual block number (in offset locations F.BKVB+2 and 
F.BKVB) 


NOTE 


When either READS or WRITES operations 
are performed, FCS maintains the 
end-of-file biock number field (F.EFBK) 
and clears the first free byte in the 
last block field F.FFBY in the FDB. 
During a READS operation, end-of-file is 
determined by the end-of-file block 
number field in F.EFBK. If desired, you 
can modify F.FFBY before closing the 
file by using the CLOSES macro call. 


3.16 WRITES - WRITE VIRTUAL BLOCK 


The WRITES macro call is issued to write a virtual block of data to a 
block-oriented device (for example, magtape, disk, DECtape, or DECtape 
II). Like the READS macro call, if certain optional parameters are 
Specified in the WRITES macro call, status information is returned to 
the I/O status block (see Section 2.8.2), and, at the completion of 
the I/O transfer, the program traps to an AST service routine that is 
supplied to coordinate asynchronous block I/O operations (see Section 
24.0%. 3) 8 


Whether or not the address of an AST service routine and/or an event 
flag number is supplied, you are responsible for synchronizing all 
block I/O processing. The WAITS macro call can be issued in 
conjunction with the WRITES macro call to suspend program execution 
until a program-dependent I/O transfer has been completed. When the 
WAITS macro call is used for this purpose, the event flag number and 
the I/O status block address in both macro calls must be the same. 
Again, as with READS operations, you should check for an error code 
immediately following the WRITES macro call as well as on return from 
the WAITS macro call. 


3.16.1 Format of WRITES Macro Call 


The WRITES macro call takes the same parameters as the READS macro 
call, as shown below. The bkvb parameter represents the symbolic 
address of a 2-word block containing the number of the virtual block 
to be written. The virtual block number is incremented automatically 
after each WRITES operation is performed. 
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The WRITES macro call has the following format: 
WRITES fdb,bkda,bkds,bkvb,bkef,bkst,bkdn,err 


When this macro call is issued, the virtual block number (that is, the 
bkvb parameter) is checked to ensure that it references a block within 
the file's allocated space; if it does, the block is written. If the 
specified block is not within the file's allocated space, FCS attempts 
to extend the file. If this attempt is successful, the block is 
written; if not, an error code indicating the reason for the failure 
of the extend operation is returned to the I/O status block and _ to 
offset location F.ERR of the associated FDB. 


If FCS determines that the file must be extended, the actual extend 
operation is performed synchronously. After the extend operation has 
been successfully completed, the WRITES operation is queued, and only 
then is control returned to the instruction immediately following the 
WRITES macro call. 


The following examples illustrate WRITES macro calls: 
WRITES RO 


WRITES #OUTFDB, #OUTBUF, #BUFSIZ,#VBNADR, #22. 


WRITES RO 
The first example specifies only the FDB address and assumes that all 
other required values are present in the FDB. The second example 
reflects explicit declarations for the FDB, the block buffer address, 
the block buffer size, the virtual block number address, and the event 
flag number for signalling block I/O completion. The third example 
Shows nuii specifications for three parameter fields, then continues 
with the event flag number, the address of the I/O status block, and 
the address of the AST service routine. Finally, the address of a 
user-coded, error-handling routine is specified. 


NOTE 
You can use RO only to pass the _ FDB 


address. Any other use of RO when you 
issue the WRITES macro call will fail. 


3.16.2 FDB Requirements for WRITES Macro Call 


WRITES operations require the presence of the same information in the 
FDB as READS operations (see Section 3.15.2). 


3.17 WAITS - WAIT FOR BLOCK I/O COMPLETION 


The WAITS macro call, which is issued only in connection with READS 
and WRITES operations, causes program execution to be suspended until 
the requested block I/O transfer is completed. This macro call may be 
used to synchronize a block I/O operation that depends on the 
successful completion of a previous block I/O transfer. 
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As noted in Section 3.15 in connection with the READS macro call, you 
can specify an event flag number through the bkef parameter. This 
event flag number is used during READS (or WRITES) operations’ to 
indicate the completion of the requested transfer. If desired, you 
can issue a WAITS macro call {specifying the same event flag number 
and I/0 status’ block address) following the READS (or WRITES) macro 
call. 


In this case, the READS (or WRITES) operation is initiated in the 
usual manner, but the Executive of the host operating system suspends 
program execution until the specified event flag is set, indicating 
that the I/0 transfer has been completed. The system then returns 
information to the I/O status block, indicating the success/failure of 
the operation. FCS then moves the I/O status block success/failure 
indicator into offset location F.ERR of the associated FDB, and 
returns with the C-bit in the Processor Status Word cleared if the 
operation is successful, or set if the operation is not successful. 
Task execution then continues with the instruction immediately 
following the WAITS macro call. 


The system returns the final status of the I/O operation to the I/0 
Status block (see Section 2.8.2) upon completion of the requested 
operation. A positive value (+) indicates successful completion, and 


a negative value (-) indicates unsuccessful completion. 


Event flags are discussed in further detail in Section 2.8.1. 


3.17.1 Format of WAITS Macro Call 
The WAITS macro call is specified in the following format: 
WAITS fdb,bkef,bkst,err 
fdb 
A symbolic value of the address of the associated FDB. 
bkef 


A numeric value specifying the event flag number to be used _ for 
synchronizing block I/O operations. The WAITS macro causes task 
execution to be suspended by invoking the WAITFOR system 
directive. This parameter must agree with the corresponding 
(bkef) parameter in the associated READS/WRITES macro call. 


If this parameter is not specified, either in the WAITS macro 
call or the associated READS/WRITE macro call, FDB offset 
location F.BKEF is assumed to contain the desired event flag 
number, as previously initialized through the bkef parameter of 
the FDBKSA or the FDBKSR macro call. 


bkst 


The symbolic address of the I/O status block in your program (see 
Section 2.8.2). Although this parameter is optional, if it is 
specified, it must agree with the corresponding (bkst) parameter 
in the associated READS/WRITES macro call. 
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If this parameter is not specified, either in the WAITS macro 
call or the associated READS/WRITES$ macro call, FDB offset 
location F.BKST is assumed to contain the address of the I/0 
status block, as previously initialized through the bkst 
parameter of the FDBKSA or the FDBKSR macro call. If F.BKST has 
not been initialized, no return of information to the I/O status 
block occurs. 
err 


The symbolic address of an optional user-coded, error-handling 
routine. 


The following statements represent WAITS macro calls: 
WAITS RO 
WAITS #INFDB, #25. 
WAITS RO,#25.,#IOSTAT 
WAITS RO, ,#IOSTAT, ERRLOC 


The first example assumes that RO contains the address of the 


associated FDB; furthermore, Since the event flag number (bkef 
parameter) is not specified. offset location F.BKEF iS assumed to 
contain the desired event flag number. If this cell in the FDB 


contains 0, event flag number 32(decimal) is used by default. 


The second example shows an explicit specification of the FDB address 
and also specifies 25(decimal) as the event flag number. Again, in 
this example, the FDB is assumed to contain the address of the I/0 
status block. In contrast, the third example shows an explicit 


specification for the address of the I/O status block. 


i 


The fourth example contains a null specification for the event flag 
number, and, in addition, specifies the address of a uSer-coded, 
error-handling routine. 


It should be noted that the WAITS macro call associated with a given 
READS or WRITES operation need not be issued immediately following the 
macro call to which it applies. For example, the following sequence 
is typical: 


1. Issue the desired READS or WRITES macro call. 


2. Perform other processing that is not dependent on the 
completion of the requested block I/O transfer. 


3. Issue the WAITS macro call. 


4, Perform the processing that is dependent on the completion of 
the requested block I/O transfer. 


When performing several asynchronous transfers in the same general 
sequence as above, a separate buffer, I/O status block, and event flag 
must be maintained for each operation. If you intend to wait for the 
completion of a given transfer, the appropriate event flag number and 
I/O status biock address must be specified in the associated WAITS 
macro call. 
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NOTE 


You can use RO only to pass the _ FDB 
address. Any other use of RO when you 
issue the WAITS macro call will fail. 


3.18 DELET$ - DELETE SPECIFIED FILE 


The DELET$ macro call causes the directory information for the file 
associated with the specified FDB to be deleted from the appropriate 
UFD. The space occupied py the file is then deallocated and returned 
for reallocation to the pool of available storage on the volume. 


This macro call can be issued for a file that is either open or 
closed. If issued for an open file, that file is then closed and 
deleted; if issued for a closed file, that file is deleted only if 
the file name string specified in the associated dataset descriptor or 
default filename block contains an explicit file version number 
(including 0 and -1l). 
NOTE 

If the DELET$ macro call is issued for 

use with a file containing sensitive 

information, it is recommended that you 

zero the file before closing it, or 

reformat the disk to destroy the 

sensitive information. (Although DELETS 

logically removes a file, the 

information physically remains on the 

volume until written over with another 


file, and could be analyzed by 
unauthorized users.) 


3.18.1 Format of DELETS Macro Call 

The DELETS macro call takes the following format: 
DELETS fdb,err 

fdb 


A symbolic value of the address of the associated 
FDB. 


err 


The symbolic address of an optional user-coded, 
error-handling routine. 


The following statements illustrate DELETS macro calls: 
DELET$S RO 
DELET$ #OUTFDB,ERRLOC 


DELET$ ROQ,ERRLOC 


CHAPTER 4 


FILE CONTROL ROUTINES 


You can invoke file control routines in MACRO-11 programs to perform 
the following functions: 


e Read or write default directory string descriptors in S$FSR2. 
e Read or write the default UIC word in SSFSR2. 

e Read or write the default file protection word in S$$FSR2. 

e Read or write the file owner word in $S$FSR2. 


e Convert a directory string from ASCII to binary, or vice 


versa. 
e Fill in all or part of a filename block from a dataset 
aescriptor and/or default filename block. 


e Find, insert, or delete a directory entry. 


e Set a pointer to a byte within a virtual block or to a record 
within a file. 


e Mark a place in a file for a subsequent OPENSx operation. 
e Issue an I/O command and wait for its completion. 

e Rename a file. 

e Extend a file. 

e Truncate a file. 

e Mark a temporary file for deletion. 

e Delete a file by filename block. 


e Perform device-specific control functions. 


4.1 CALLING FILE CONTROL ROUTINES 
The CALL opcode/macro is used to invoke file control routines (JSR PC, 
dst). These routines are included from the system object library 
({1,1]SYSLIB.OLB) at task-build time and incorporated into the user 
task. The file control routines are called as shown below: 

CALL » RDFDR 


CALL .- EXTND 
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Before the CALL is issued, certain file control routines require that 
specific registers be preset with requisite information. These 
requirements are identified in the descriptions of the respective 
routines. Upon return, all registers are preserved, except those 
explicitly specified as changed. 


If an error is detected by a file control routine, the C-bit (carry 
condition code) in the Processor Status Word is set, and an error 
indication is returned to FDB offset location F.ERR. However, certain 
file control routines do not return error indications. The following 
file control routines are listed according to whether they return 
error indications. 


Normal Error Return 


(C-bit and F.ERR) No Error Return 
~ASCPP «RDFDR 
« PARSE ~WDFDR 
- PRSDV ~RDFUI 
« PRSDI ~WDFUTI 
- PRSDV - RDFFP 
- ASLUN ~WDFFP 
~FIND - RFOWN 
~ ENTER -WFOWN 
« REMOV « PPASC 
~GTDIR MARK 
~GTDID 
- POINT 
« POSRC 
-POSIT 
-~XOIO 
- RENAM 
- EXTND 
~TRNCL 
-MRKDL 
- DLFNB 
CTRL 


Appendix I lists the error codes that the routines identified above 
return in FDB offset location F.ERR. 


4.2 DEFAULT DIRECTORY-STRING ROUTINES 


The .~.RDFDR and .WDFDR routines are used to read and write directory 
string descriptors. 


4.2.1 .RDFDR - Read $S$FSR2 Default Directory String Descriptor 


You call the .RDFDR routine to read default directory string 
descriptor words previously written by the .WDFDR routine into program 
section $S$FSR2 of the FSR. These descriptor words define the address 
and the length of an ASCII string that contains the default directory 
string. This directory string constitutes the default directory that 
is to be used by FCS when one is not explicitly specified in a dataset 
descriptor. 
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If you have not established default directory string descriptor words 
in $SFSR2 through the .WDFDR routine described below, the descriptor 
words in $$FSR2 are null and FCS uses a default directory (when one is 
not specified in a dataset descriptor) corresponding to the UIC under 
which the task is running. 


When called, the .RDFDR routine returns values in the _ following 
registers: 


Rl Contains the size (in bytes) of the default directory string 
in S$SFSR2. 


R2 Contains the address of the default directory string in 
SSFSR2. If no default directory string descriptor words have 
been written by .WDFDR, R2 equals 0. 


4.2.2 .WDFDR - Write New S$$FSR2 Default Directory-String Descriptor 


The .WDFDR routine is called to create default directory string 
descriptor words in S$SFSR2. For example, if your program is to 
operate on files in the directory [220,220], regardless of the UIC 
under which the program runs, then you can establish default directory 
string descriptor cells in $$FSR2 to point to the alternate directory 
string [220,220] created elsewhere in the program. To do this, the 
desired directory string is first created through an .ASCII directive. 
Then, by calling the .WDFDR routine, you can initialize the default 
directory string descriptor cells in S$$FSR2 to point to the new 


Assume that the task is currently running under default UIC [200,200]. 
By issuing a MACRO-11 directive similar to the following: 

NEWDDS: eASCII /[220,2201/ 
you define a new directory string. Then, by calling the .WDFDR 
routine, you can initialize string descriptor cells in S$SFSR2 to point 
to the new directory string. 
The following registers must be preset before calling the .WDFDR 
routine: 


Rl Must contain the size (in bytes) of the new directory string. 


R2 Must contain the address of the new directory string. 


NOTE 


Establishing default directory string 
descriptor words in S$SFSR2 does not 
change the default UIC in $$FSR2 or the 
task's privileges. 
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4.3 DEFAULT UIC ROUTINES 


The .RDFUI and .WDFUI routines are used to read and write the default 
UIC maintained in program section $S$FSR2 of the file storage region 
(FSR). Unlike the default directory string descriptor that describes 
an ASCII string, the default UIC is maintained as a binary value with 
the following format: 


Bit 15 8 7 0 


a oe 


The default UIC in SSFSR2 provides directory identification 
information for a file being accessed. FCS uses it only when all 
other sources of such information have failed to specify a directory 
(refer to Section 4.7.1.2). It is never used to establish file 
ownership or file access privileges. 


Unless you explicitly change the default UIC through the .WDFUI 
routine described below, the default UIC in S$$FSR2 always corresponds 
to the UIC under which the task is running. 


4.3.1 .RDFUI - Read Default UIC 
When called, the .RDFUI routine returns the default UIC as follows: 


Rl Contains the binary encoded default UIC aS maintained in 
program section S$S$FSR2. 


4.3.2 .WDFUI - Write Default UIC 
The .WDFUI routine is called to create a new default UIC in S$SFSR2. 


The following register must be preset before calling the .WDFUI 
routine: 


Rl Must contain the binary representation (as shown above) of a 
UIC. 


NOTE 


The .WDFUI routine overrides any default 
UIC descriptor previously created by 
-WDFDR in SSFSR2. 


4.4 DEFAULT FILE-PROTECTION WORD ROUTINES 


The .~.RDFFP and .WDFFP routines described below are used to read _ and 
write the default file protection word in a location in program 
section SSFSR2 of the file storage region (FSR). This word is’ used 
only at file creation time (for example, by the OPENSW macro call) to 
establish the default file protection values for the new file. Unless 
altered, this value constitutes the default file protection word for 
that file. If the value is -l, it indicates that the volume default 
file protection value is to be used for the new file. 
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The default file protection word has the following format: 


Bit 15 si Aa 8 8 7 4 3 0 


WORLD GROUP OWNER SYSTEM 


Each of the four categories above has four bits; each bit has the 
SS: 


i 
following meaning with respect to file access 


Bit 3 2 1 0 


DELETE | EXTEND | WRITE READ 


A bit value of 0 indicates that the respective type of access to the 
file is to be allowed; a bit value of 1 indicates that the respective 
type of access to the file is to be denied. 


4.4.1 .RDFFP - Read SSFSR2 Default File Protection Word 


You call the .RDFFP routine to read the default file protection word 
in program section $$FSR2 of the FSR. No registers need be set before 
calling this routine. 


When called, the .RDFFP routine returns the following information: 


Rl Contains the default file protection word from S$S$FSR2. 


4.4.2  .WDFFP — Write New SSFSR2 Default File-Protection Word 


The .WDFFP routine is used to write a new default file protection word 
into $$FSR2. 


The following register must be preset before calling this routine: 


Rl Must contain the new default file protection word to be 
written into S$SFSR2. If this register is set to -l, the 
default file protection values established through the 
appropriate operating system command will be used in creating 
all subsequent new files. 


4.5 FILE OWNER WORD ROUTINES 


The file owner word, like the default file protection word above, is.a 
location in program section S$FSR2 of the FSR. Its contents are 
specified by the current program through the .WFOWN routine. If not 
so specified, the file owner word contains 0. 


For nonprivileged users, the owner of a new file corresponds to the 
default UIC specification, as follows: 


e If the volume on which the new file is created is private 
(allocated), the owning UIC is the same as the UIC of the task 
creating the file. 


e If the volume on which the new file is created is a _ system 
volume, the owning UIC is the same as the task's login UIC. 
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For privileged users, the owning UIC is always the same as the UIC of 
the task creating the file. 


Note that for files created by privileged or nonprivileged tasks that 
are started by a time-scheduled request, the owning UIC is set to the 
UIC specified at task-build time. 


A specific UIC value can be stored in the file owner word by the 
e-WFOWN routine (see Section 4.5.2). All new files then created and 
closed by your task will contain the specified UIC value. 


The format of the file owner word is shown below: 


Bit 15 8 7 0 


The routines for reading and writing the file owner word are described 
below. 


NOTES 


1. The UIC and the file protection word 
for the file (see Section 4.4) must 
not be set such that the UIC under 
which the task is running does not 
have access to the file. This 
condition results in a= privilege 
violation. 


2. When a file is created, its owning 
UIC is always set to either the UIC 
of the task creating the file or the 
task's login UIC, as previously 
described. However, when closing 
the file, you can change the owning 
UIC by using the .WFOWN routine. If 
the file is not closed properly, the 
owning UIC will not change. 


4.5.1 .RFOWN —- Read S$SFSR2 File Owner Word 


The .RFOWN routine is used to read the contents of the file owner word 
in S$S$FSR2. No registers need be preset before calling this routine. 


When called, the .RFOWN routine returns the following information: 
Rl Contains the file owner word (UIC). If the current program 


has not previously established the contents of the file 
owner word through the .WFOWN routine, Rl contains 0. 


4.5.2  .WFOWN —- Write New SSFSR2 File Owner Word 


The .WFOWN routine is used to initialize the file owner word in 
SSFSR2. 


The following register must be preset before calling this routine: 


Rl Must contain a file owner word to be written into SSFSR2. 


FILE CONTROL ROUTINES 


4.6 ASCII/BINARY UIC CONVERSION ROUTINES 


The .ASCPP and .PPASC routines are called to convert a directory 
string from ASCII to binary, or vice versa. 


4.6.1 .ASCPP - Convert ASCII Directory String to Equivalent Binary UIC 


The .ASCPP routine is called to convert an ASCII directory string to 
its corresponding binary UIC. 


The following registers must be preset before calling this routine: 


R2 Must contain the address of the directory string descriptor 
in your program (see Section 2.4.1) for the string to be 
converted. 


R3 Must contain the address of a word location in your program 
to which the binary UIC is to be returned. The member 
number is stored in the low-order byte of the word, and the 
group number is stored in the high-order byte. 


4.6.2 .PPASC - Convert UIC to ASCII Directory String 


The .PPASC routine is called to convert a binary UIC to its 
corresponding ASCII directory string. 


The following registers must be preset before calling this routine: 


R2 Must contain the address of a storage area within your 
program into which the ASCII string is to be placed. The 
resultant string can be up to nine bytes in length, for 
example, [200,200]. 


R3 Must contain the binary UIC value to be converted. The 
low-order byte of the register contains the member number, 
and the high-order byte of the register contains the group 
number. 


R4 Must contain a control code. Bits 0 and 1 of this’ register 
indicate the following: 


Bit 0 is set to 0 to suppress leading zeros (for example, 001 
is returned as 1). Bit 0 is set to 1 to indicate that 
leading zeros are not to be suppressed. 


Bit 1 is set to 0 to place Separators (square brackets and 
commas) in the directory string (for example, [10,20]). 
Bit 1 is set to 1 to suppress separators (for example, 
1020). 


The .PPASC routine increments the contents of R2 to point to the byte 
immediately following the last byte in the converted directory string. 


4.7 FILENAME BLOCK ROUTINES 


The .PARSE, .~.PRSDV, .PRSDI, .PRSFN, and .ASLUN routines are available 
for performing functions related to a specified filename block. These 
routines are described in the following sections. 
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4.7.1  .PARSE - Fill in All Filename Information 


When called, the .PARSE routine first zeros the filename block pointed 


to by Rl and then stores the following information in the filename 
block: 


1. The ASCII device name (N.DVNM) 

2. The binary unit number (N.UNIT) 

3. The directory ID (N.DID) 

4. The Radix-50 file name (N.FNAM) 

5. The Radix-50 file type or extension (N.FTYP) 
6. The binary file version number (N.FVER). 


For ANSI magnetic tape file names, the following information is stored 
in the filename block: 


1. The ASCII device name (N.DVNM) 

2. The binary unit number (N.UNIT) 

3. The file name as 17 ASCII bytes (N.ANM1 and N.ANM2) 
4. The binary file version number (N.FVER) 


In addition, .PARSE calls .ASLUN to assign the LUN associated with the 
FDB to the device and unit currently specified in the filename block. 


Both formats for filename blocks are shown in detail in Appendix B. 


Before the .PARSE routine can be called, the FINIT$ macro call (see 
Section 2.6) must be invoked explicitly in your program, or it must be 
invoked implicitly through a prior OPENSx macro call. Note, however, 
that the FINIT$ call must be issued only once in the initialization 
section of the program; that is, the FINITS operation must be 
performed only once per task execution. Furthermore, FORTRAN programs 
issue a FINITS call at the beginning of task execution; therefore, 
MACRO-11 routines used with the FORTRAN object time system must not 
issue a FINITS$ macro call. 


The following registers must be preset before calling the .PARSE 
routine: 


RO Must contain the address of the desired FDB. 


Rl Must contain the address of the filename block to be filled 
in. This filename block is usually, but not necessarily, the 
filename block within the FDB specified in RO (that is, RO + 
F.FNB). 


R2 Must contain the address of the desired dataset descriptor if 
-PARSE is to access a dataset descriptor in building the 
specified filename block. This structure is usually, but not 
necessarily, the same as that associated with the FDB 
specified in RO (that is, the dataset descriptor pointed _ to 
by the address value in F.DSPT). 


If R2 contains 0, this value implies that a dataset 
descriptor has not been defined; therefore, the dataset 
descriptor logic of .PARSE is bypassed. 
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R3 Must contain the address of the desired default filename 
block if .PARSE is to access a default filename block in 
building the specified filename block. This structure is 
usually, but not necessarily, the same as that associated 
with the FDB specified in RO (that is, the default filename 
block pointed to by the address value in F.DFNB). 


If R3 contains zero (0), this value implies that a default 
filename block has not been defined; therefore, the default 
filename block logic of .PARSE is bypassed. 


Thus, RO and Rl each must contain the address of the appropriate data 
Structure, while either R2 or R3 must contain the address of the 
desired filename information. Both R2 and R3, however, may contain 
address values if the referenced structures both contain information 
required in building the specified filename block. 


The .PARSE routine fills in the specified filename block in the order 
described in the following sections. 


4.7.1.1 Device and Unit Information - The » PARSE routine first 
attempts to fill in the filename block with device (N.DVNM) and unit 
(N.UNIT) information. The following operations are performed in 
sequence until the required information is obtained from the specified 
data structures: 


l. If the address of a dataset descriptor is specified in R2 and 
this structure contains a device string, the device and unit 
information therein is moved into the specified filename 
block. 


2. If step 1 fails, and if the address of a default filename 
block is specified in R3, and this structure contains a 
nonzero value in the device name field, the device and unit 
information therein is moved into the specified filename 
block. 


3. If step 2 fails, .PARSE uses the device and unit currently 
assigned to the logical unit number in offset location F.LUN 
of the specified FDB in building the filename block. 


This feature allows a program to use preassigned logical 
units that are assigned through either the device assignment 
(ASG) option of the Task Builder or one of the following 
commands: ASSIGN (under IAS) or REASSIGN (under RSX-11). In 
this case, you simply avoid specifying the device string in 
the dataset descriptor and the device name in the default 
filename block. 


4. If the logical unit number in F.LUN is currently unassigned, 
-PARSE assigns this number to the system device (SY0:). 


Once the device and unit are determined and the logical unit number is 
assigned, .PARSE invokes the GLUNS directive to obtain necessary 
device information. Requisite information is returned to the 
following offsets in the filename block pointed to by Rl: 


N.DVNM - Device Name Field. Contains the redirected device 
name. 

N.UNIT - Unit Number Field. Contains the redirected unit 
number. 
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In addition, requisite information is returned to the following 
offsets in the FDB pointed to by RO: 


F.RCTL - Device Characteristics Byte. This cell contains 


device-dependent information from the first byte of the 
third word returned by the GLUNS directive. The bit 
definitions pertaining to the device characteristics 
byte are described in detail in Table A-l. If desired, 
you can examine this cell in the FDB to determine the 
characteristics of the device associated with the 
assigned LUN. 


F.VBSZ - Device Buffer Size Word. This location contains’ the 


information from the sixth word returned by the GLUNS 
directive. The value in this cell defines the device 
buffer size (in bytes) pertaining to the device 
associated with the assigned LUN. 


The GLUNS directive is described in detail in the Executive Reference 
Manual of the host operating system. 


4.7.1.2 Directory Identification Information - Following the opera- 


tions 


described in the preceding section, .PARSE attempts to fill in 


the filename block with directory identification information (N.DID). 
The precedence rules for establishing this information are as follows: 


l. 


If the address of a dataset descriptor is specified in RZ and 
this structure contains a directory string, that directory 
string is used to find the associated UFD in the MFD. The 
resulting file ID is then moved into the directory-ID field 
of the specified filename block. 


If step 1 fails, and if the address of a default filename 
block is specified in R3, and this structure contains a 
nonzero directory ID, it is moved into the specified filename 
block. 


a tha 
Since none of the parameters of the NMBLKS Mm 


Section 2.4.2) inftialize the three words starting at offset 
location N.DID in the default filename block, these cells 
must be initialized manually, or by issuing a call to either 
the .GTDIR routine (see Section 4.9.1) or the .GTDID routine 
(see Section 4.9.2). Note that these routines can also be 
used to initialize a specified filename block directly with 
required directory information. 


o 
1 


If neither step 1 nor step 2 yields the required directory 
string, .PARSE examines the default directory string words in 
SSFSR2. If your program has previously initialized these 
words through use of the .WDFDR routine, FCS uses the string 
described as the default directory. 


If steps 1 through 3 fail to produce directory information, 
FCS uses the binary value stored in the default UIC word in 
SSFSR2 as the directory identifier. Unless changed by you 
through the .WDFUI routine, this word contains the UIC under 
which the task is running. 
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NOTE 


Wildcard UICsS are not acceptable to 
- PARSE. In addition, .PARSE will not 
set either filename block status word 
(N.STAT) bits NB.SD1 or NB.SD2 (group 
and owner wildcard specifications, 
respectively). 


4.7.1.3 File Name, File Type or Extension, and File Version Information 
- Following the operations described in the preceding section, .PARSE 
attempts to obtain file name information (N.FNAM, N.FTYP, and N.FVER), 
as follows: 


1. If the address of a dataset descriptor is specified in R2 and 
this structure contains a filename string, the file name 
information therein is moved into the specified filename 
block. 


2. If the address of a default filename block is specified in 
R3, and one or more of the file name, file type or extension, 
and file version number fields of the dataset descriptor 
specified in R2 are null, then the corresponding fields of 
the default filename block are used to fill in the specified 
filename block. 


3. If neither step 1 nor step 2 yields the requisite file name 
information, any specific fields not available from either 
source remain null. 


NOTE 


If a dot (.) appears in the file name 
string without an accompanying file type 
designation (for example, TEST. or 
TEST.;3), the file type is interpreted 
as being explicitly null. In this case, 
the default file type is not’ used. 
Similarly, if a semicolon (;) appears in 
the file name string without an 
accompanying file version number (for 
example, TEST.DAT;), the file version 
number is also interpreted as_ being 
explicitly null; again, the default 
file version number is not used in this 
case. This note (except for the version 
number) does not apply to the 17-byte 
ASCII file name strings supported for 
ANSI magnetic tape. 


4.7.1.4 Other Filename Block Information - Finally, after performing 
all the operations above, the .PARSE routine also fills in the 
filename block status word (offset location N.STAT) of the file name 
block specified in Rl. 


The bit definitions for this word are presented in Table B-2. Note in 
this table that an "explicit" directory, device, file name, file type, 
or file version number specification pertains to ASCII data supplied 
through the dataset descriptor pointed to by R2. 
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In addition, .PARSE explicitly zeros offset location N.NEXT in the 
filename block pointed to by Rl. This action has implications for 
wildcard operations, as described in Section 4.8.1 below. 


4.7.2 .PRSDV - Fill in Device and Unit Information Only 


The .PRSDV routine is identical to the .PARSE routine above, except 
that it performs only those operations associated with requisite 
device and unit information (see Section 4.7.1.1). This routine zeros 
the filename block pointed to by Rl, performs a .PARSE operation on 
the device and unit fields in the specified dataset descriptor and/or 
default filename block, and assigns the logical unit number contained 
in offset location F.LUN of the specified FDB. 


4.7.3  .PRSDI - Fill in Directory Identification Information Only 


The .PRSDI routine is identical to the .PARSE routine above, except 
that it performs only those operations associated with requisite 
directory identification information (see Section 4.7.1.2). This 
routine performs a .PARSE operation on the directory identification 
information (N.DID) field in the specified dataset descriptor and/or 
default filename block. 


4.7.4 .PRSFN - Fill in File name, File Type or Extension, and File Version Only 


The .~PRSFN routine is identical to the .PARSE routine above, except 
that it performs only those operations associated with requisite file 
name, file type or extension, and file version information (see 
Section 4.7.1.3). This routine performs a .PARSE operation on the 
file name, file type or extension, and file version information fields 
(N.FNAM, N.FTYP, N.FVER) in the specified dataset descriptor and/or 
default filename block. 


4.7.5 .ASLUN - Assign Logical Unit Number 


The .ASLUN routine is called to assign a logical unit number to a 
specified device and unit and to return the device information to a 
specified FDB and filename block. 


The following registers must be preset before calling this routine: 


RO Must contain the address of the desired FDB. 
J 
Rl Must contain the address of the filename block containing the 
desired device and unit. This filename block is usually, but 
not necessarily, the filename block within the FDB specified 
in RO. 


If the device name field (offset location N.DVNM) of the filename 
block pointed to by Rl contains a nonzero value, the specified device 
and unit are assigned to the logical unit number contained in offset 
location F.LUN in the FDB pointed to by RO. 


If N.DVNM in the filename block contains 0, then the device and unit 


currently assigned to the specified logical unit number are returned 
to the appropriate fields of the filename block. 
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Finally, if the specified logical unit number is not assigned to a 
device, the .ASLUN routine assigns it to the system device (SY0:) by 
default. 


The information returned to the specified filename block and to the 
specified FDB is identical to that returned by the device and unit 
logic of the .PARSE routine (see Section 4.7.1.1). 


4.8 DIRECTORY ENTRY ROUTINES 


The .FIND, .ENTER, and .REMOV routines are used to find, insert, and 
delete directory entries. The term "directory entry" encompasses 
entries in both the Master File Directory (MFD) and the User File 
Directory (UFD). 


4.8.1 .FIND - Locate Directory Entry 


The .FIND routine is called to locate a directory entry by file name 
and to fill in the file identification field (N.FID) of a specified 
filename block. 


The following registers must be preset before calling this routine: 
RO Must contain the address of the desired FDB. 


Rl Must contain the address of a filename block. This filename 
block is usually, but not necessarily, the filename block 
within the FDB specified in RO. 


When invoked, the .FIND routine searches the directory file specified 
by the directory-ID field of the filename block. This file is 
searched for an entry that matches the specified file name, file type, 
and file version number. In this regard, two special file versions 
are defined: 


e Version 0 is matched by the latest (largest) version number 
encountered in the directory file. 


e Version -1l is matched by the oldest (smallest) version number 
encountered in the directory file. 


If either of these special versions is specified in the filename 
block, the matching version number is returned to the filename block. 
In this way, the actual version number is made available to the 
program. 


Certain wildcard operations require the use of the .FIND routine. 
Three bits in the filename block status word (see N.STAT in Table B-2) 
indicate whether a wildcard (*) was specified for a file name, a file 
type, or a file version number field. If the wildcard bit in N.STAT 
is set for a given field, any directory entry matches in that 
corresponding field. Thus, if the file name and file version number 
fields contain wildcard specifications (*), and the file type field is 
specified as .OBJ (that is, *.OBJ;*), the first directory entry 
encountered that contains .OBJ in the file type field matches, 
regardless of the values present in the other two fields. 
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When a wildcard match is found, the complete file name, file type, and 
file version number fields of the matching entry are returned to the 
filename block, along with the file-ID field (N.DID). Thus, the 
program can determine the actual name of the file just found. Offset 
location N.NEXT in the filename block is also set to indicate where 
that directory entry was found in the directory file. This 
information is used in subsequent .FIND operations to locate the next 
matching entry in the directory file. 


For example, the .FIND routine is often used to open a series of files 
when wildcard specifications are used. The following operations are 
typical: 


1. Call the .PARSE routine. This routine zeros offset location 
N.NEXT in the filename block in preparation for the iterative 
-FIND operations described in step 3 below. 


2. Check for wildcard bits set by the .PARSE routine in the 
filename block status word (see N.STAT in Table B-2). An 
instruction sequence such as that shown below may be used to 
test for the setting of wildcard bits in N.STAT: 


BIT #NB.SVR!NB.STP!NB.SNM,N.STAT(R1) 
BEQ NOWILD ;BRANCH IF NOT SET. 


3. If wildcard specifications are present in the filename block 
status word, repeat the following sequence until all the 
desired wildcard files have been processed: 


CALL .FIND 


BCS DONE ;ERROR CODE IE.NSF INDICATES 
;NORMAL TERMINATION. 


OPENS RO 


Wildcard .FIND operations update offset location N.NEXT in 
the filename block. In essence, the contents of this cell 


eritA bw NAMA man et SRA ems fnawr naN manvrw 
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of the directory file for a matching entry. 


4. Perform the desired operations on the file. 


NOTE 


The above procedure applies only for the 
following types of wildcard file 
specifications: 


TEST.DAT;* 
TEST.¥*;* 
* DAT; * 
TEST.*:5 
* DAT;3 


The procedure does not work for. the 
following types of wildcard file 
specifications: 


* DAT 
TEST.* 
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In summary, if a wildcard file 
specification is present in either the 
file name field or the file type field, 
the file version number field must also 
contain either an explicit wildcard 
specification (*) or a specific file 
version number (for example, 2, 3, and 
so forth). In the latter case, however, 
the version number cannot be 0, for’ the 
latest version of the file, or -l, for 
the oldest version of the file. 


When your task sets NB.ANS, the .FIND operation compares the file name 
against the full 17-character ANSI file name string that is stored in 
the filename block (see Appendix B). When NB.ANS is clear, the file 
name is converted to Radix-50, as described in Appendix G. 


ANSI magnetic tape file names in the following formats can be 
converted to Radix-50: 


e Up to nine Radix-50 characters followed by spaces 


e Up to nine Radix-50 characters followed by a dot, followed by 
spaces or by a 3-character file type 


Note that unless NB.ANS is set before the call to .FIND, some _ file 
names may be incorrectly matched. For example, the names "ABC" and 
"ABC." are considered the same when compared with the name ABC in 
Radix-50. 


When a wildcard operation is performed, the name returned in the 
filename block is normally converted to Radix-50. However, if NB.ANS 
is set, the ANSI file name string is returned as up to 17 ASCII bytes. 
The first twelve bytes are returned at offset N.ANM1 in the ANSI 
filename block. The remainder are returned at offset N.ANM2. 


It is illegal to set NB.ANS before a wildcard .FIND operation unless 
both file name and file type are wild, or both filename and file type 
are not wild. 


To delete a file whose file descriptor entry in the FDB_ contains 
wildcards, you must save the values in the fields N.STAT and N.NEXT in 
the FDB, then zero those fields in the FDB. A DELETE call then uses 
the information returned from the last .FIND to delete the file. Once 
the file is deleted, the saved values of N.STAT and N.NEXT must be 
restored in the FDB. 


4.8.2 .ENTER - Insert Directory Entry 


The .ENTER routine is used to insert an entry by file name into a 
directory. 


The following registers must be preset before calling this routine: 
RO Must contain the address of the desired FDB. 
Rl Must contain the address of a filename block. This filename 


block is usually, but not necessarily, the filename block 
within the FDB specified in RO. 
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Tf the file version number field of the filename block contains 0, 
indicating a default version number, the .ENTER routine scans the 
entire directory file to determine the current highest version number 
for the file. If a version number for the file is found, this entry 
is incremented to the next higher version number; otherwise, it is 
set to 1. The resulting version number is returned to the filename 
block, making this number known to the program. 


NOTE 


Wildcard specifications cannot be used 
in connection with .ENTER operations. 


4.8.3  .REMOV - Delete Directory Entry 


The .REMOV routine is called to delete an entry from a directory by 
file name. This routine only deletes a specified directory entry; it 
does not delete the associated file. 


The following registers must be preset before calling this routine: 
RO Must contain the address of the desired FDB. 


Rl Must contain the address of a filename block. This filename 
block is usually, but not necessarily, the filename block 
within the FDB specified in RO. 


Wildcard specifications operate in the same manner as for the  .FIND 
routine described in Section 4.8.1 above. The file version number for 
-REMOV operations must be explicit (including 0 and -1) or wildcard. 
Each .REMOV operation deletes the next directory entry having the 
specified file name, file type, and file version number. 


4.9 FILENAME BLOCK ROUTINES 


The .GTDIR and .GTDID routines are used _ to insert directory 
information in a specified filename block. 


4.9.1 .GTDIR - Insert Directory Information in Filename Block 


The .GTDIR routine is called to insert directory information taken 
from a directory string descriptor into a specified filename block. 


Before calling this routine, the following registers must be preset: 
RO Must contain the address of the desired FDB. 


Rl Must contain the address of a filename block in which the 
directory information is to be placed. This filename block 
is usually, but not necessarily, the filename block within 
the FDB specified in RO. 


R2 Must contain the address of the 2-word directory string 
descriptor in your program. This string descriptor defines 
the size and the address of the desired directory string. 
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This routine performs a .FIND operation for the specified UFD in the 
MFD and returns the resulting directory ID to the three words of the 
specified filename block, starting at offset location N.DID. The 
-GTDIR routine preserves the information in offset locations N.FNAM, 
N.FYTP, N.FVER, N.DVNM, and N.UNIT of the filename block, but zeros 
(clears) the rest of the filename block. 


The .GTDIR routine can also be used in conjunction with the NMBLKS 
macro call (see Section 2.4.2) to insert directory information into a 
specified default filename block. 


4.9.2 .GTDID - Insert Default Directory Information in Filename Block 


The .GTDID routine provides an alternative means for inserting 
directory information into a specified filename block. Instead of 
allowing the specification of the directory string, as does the .GTDIR 
routine above, this routine uses the binary value found in the default 
UIC word maintained in $$FSR2 as the desired UFD. 


Before calling this routine, the following registers must be preset: 
RO Must contain the address of the desired FDB. 


Rl Must contain the address of a filename block in which the 
directory information is to be placed. This filename block 
is usually, but not necessarily, the filename block within 
the FDB specified in RO. 


When called, the .GTDID routine takes the default UIC from its 1-word 
location in SSFSR2 and performs a .FIND operation for the associated 
UFD in the MFD. The resulting directory ID is returned to the three 
words of the specified filename block, starting at offset location 
N.DID. As does the .GTDIR routine, .GTDID preserves offset locations 
N.FNAM, N.FTYP, N.FVER, N.DVNM, and N.UNIT in the filename block, but 
zeros the rest of the filename block. 


The .GTDID routine embodies considerably less code than the .GTDIR 


routine. Its input is the binary representation of a UIC rather than 
an ASCII string descriptor. Therefore, it does not invoke the .PARSE 
logic; furthermore, .GTDID is intended specifically for use in 


programs that open files by the OFNBS macro call (see Section 3.6). 
Such a program does not invoke the .PARSE logic because all required 
file name information is provided to the program in filename block 
format. 


As is true of the .GTDIR routine described in Section 4.9.1 above, 
-GTDID can be used in conjunction with the NMBLKS macro call (see 
Section 2.4.2) to insert directory information (N.DID) into a 
specified default filename block. You also have the option to 
initialize offset location N.DID manually with required directory 
information. 


4.10 FILE POINTER ROUTINES 


The .~POINT, .POSRC, .MARK, and .POSIT routines are used to point to a 
byte or a record within a specified file. 
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4.10.1 .POINT - Position File to Specified Byte 


The .POINT routine is called to position a file to a specified byte in 
a specified virtual block. If locate mode is in effect for record I/O 
Operations, the .POINT routine also updates the value in offset 
location F.NRBD+2 in the associated FDB in preparation for a PUTS 
operation in locate mode. 


The following registers must be preset before calling this routine: 
RO Must contain the address of the desired FDB. 
Rl Must contain the high-order bits of the virtual block number. 
R2 Must contain the low-order bits of the virtual block number. 


R3 Must contain the desired byte number within the specified 
virtual block. 


For a description of virtual block numbers and how these 2-word values 
are formed, refer to item 4 in Section 2.2.2.1. 


NOTE 


Using the .POINT routine is’ restricted 
to files accessed with GETS or PUTS 
macros. For files accessed with READS 
or WRITES macros, use the FDBKSR macro 
to initialize the block access’ section 
of the FDB. 


The .POINT routine is often used in conjunction with the .MARK routine 
to achieve a limited degree of random access with variable-length 
records. The .MARK routine saves the positional context of a file in 
anticipation of temporarily closing that file and then reopening it 
later at the same position. For such purposes, the _ following 
nena ns = S: 

1. Call the .MARK routine (see Section 4.10.3 below) to save the 

current positional context of the file. 


2. Close the file. 

3. When desired, reopen the file. 

4. Load the information returned by the .MARK routine into Rl, 
R2, and R3, as required above, before calling the .POINT 
routine. 

5. Call the .POINT routine. 

The .POINT routine may be called to rewind a file on disk or 
ANSI magtape to its start. For this case, Rl and R3 must be 
0, and R2 must be l. 

The .POINT routine may be called to rewind a file that is 
open on a terminal. Doing so clears the terminal end-of-file 


condition. 


6. Resume processing of the file. 
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4.10.2 .POSRC - Position File to Specified Record 


The .POSRC routine is called to position a file to a_ specified 
fixed-length record within a file. If locate mode is in effect for 
record I/O operations, the .~.POSRC routine alSo updates the value in 
offset location F.NRBD+2 in the associated FDB in preparation for a 
PUTS operation in locate mode. 


Before calling this routine, you must set offset locations F.RCNM+2 
and F.RCNM in the FDB to the desired record number and ensure that the 
correct record size is reflected in offset location F.RSIZ of the FDB. 


Also, the register below must be preset before calling the .POSRC 
routine: 


RO Must contain the address of the associated FDB. 


The .POSRC routine is used when performing random access’ PUTS 
operations in locate mode. Normally, PUTS operations in locate mode 
are sequential; however, when random access mode is used, the 
following procedure must be performed to ensure that the record is 
built at the desired location: 


1. Set offset locations F.RCNM+2 and F.RCNM in the associated 
FDB to the desired record number. 


2. Call the .POSRC routine. 


3. Build the new record at the address returned (by the .POSRC 
call) in offset location F.NRBD+2 of the associated FDB. 


4, Perform the PUTS operation. 


4.10.3 .MARK - Save Positional Context of File 


The .MARK routine allows you to record the current positional context 
of a file for later use. For example, you can mark the current 
position of the file, close that file, and later reopen the file and 
return to the same position within it. The .MARK routine is also 
useful in altering records within a file. After determining the 
record to be altered, you can save your position in the file and 
retrieve information elsewhere in the file for use in updating the 
desired record. Then, by returning to the saved position of the file, 
you can alter the desired record. This iterative sequence may be 
repeated any number of times to update desired records in the file. 


RO must contain the address of the associated FDB before calling this 
routine. 


When called, the .MARK routine returns information to the following 
registers: 


Rl Contains the high-order bits of the virtual block number. 
R2 Contains the low-order bits of the virtual block number. 


R3 Contains the number of the next byte within the virtual 
block. 


R3 points to the next byte in the block. For example, if four GETS 
operations are performed, followed by a call to the .MARK routine, R3 
points to the first byte in the fifth record in the file. 
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4.10.4 .POSIT - Return Positional Information for Specified Record 


The .POSIT routine calculates the virtual block number and the byte 
number pertaining to the beginning of a specified record. 


The following register must be preset before calling this routine: 
RO Must contain the address of the associated FDB. 


In addition, offset locations F.RCNM and F.RCNM+2 in the associated 
FDB must contain the desired record number. 


Unlike the .POSRC routine above, which positions the file to the 
specified record, .POSIT simply calculates the positional information 
for a specified record so that a .POINT operation can be later 
performed to position to the desired record. 


The register values returned by the .POSIT routine are identical to 
those described above for the .MARK routine. 


4.11 QUEUE I/O FUNCTION ROUTINE (.XQIO) 


The .XQIO routine is called to execute a specified Queue I/O function 
and to wait for its completion. 


The following registers must be preset before calling this routine: 


RO Must contain the address of the desired FDB. 

Rl Must contain the desired Queue I/O function code. Refer to 
the IAS Device Handlers Reference Manual or the 
RSX-11M/M-PLUS I/O Drivers Reference Manual for the desired 


R2 Must contain the number of optional parameters, if any, to be 
included in the Queue I/O directive. 


R3 Must contain the beginning address of the list of optional 
Queue I/0 directive parameters, if R2 contains a nonzero 
value. Refer to the RSX-l11M/M-PLUS I/0 Drivers Reference 
Manual for the parameter list. =e. 


4.12 RENAME FILE ROUTINE (.RENAM) 


The .RENAM routine is called to change the name of a file in its 
associated directory. To rename a file, you must specify the address 
of an FDB containing file name information, a LUN, and an event flag 
number to be used in connection with renaming the file. 


If the file to be renamed is open when the call to .RENAM is’ issued, 
that file is closed before the renaming operation is attempted. 


The following registers must be preset before calling this routine: 


RO Must contain the address of the FDB associated with the 
originally named file. 


Rl Must contain the address of the FDB containing the desired 
file name information, LUN assignment, and event flag to be 
associated with renaming the file. 


FILE CONTROL ROUTINES 


If the renaming operation is successful, a new directory entry is 
created, and the original entry is deleted. If the operation is not 
successful, the file is closed under its original name, and the 
associated directory is not affected. 


The .RENAM routine uses the absence of a value in location F.FNB4+N.FID 
to indicate that .PARSE must be called to parse a file specification 
(an open file always has a nonzero value in F.FNB + N.FID). If 
neither a dataset descriptor nor a default filename block is present, 
-PARSE returns a null file name. The rename operation then results in 
a new file name of ".;1". 


NOTE 


The renaming process is merely a 
directory operation that replaces an old 
entry with a new entry. The file name 
stored in the file header block is not 
altered. 


2-13 FILE EXTENSION ROUTINE (.EXTND) 


The .EXTND routine is called to extend either contiguous or 
noncontiguous files. The file to be extended can be either open or 
closed. A call to the .EXTND routine disables automatic file 
truncation. 


The following registers must be preset before calling this routine: 
RO Must contain the address of the associated FDB. 


Rl Must contain a numeric value specifying the number of blocks 
to be added ts the file. 


R2 Must contain the extension control bits, as appropriate. The 
possible bit configurations for controlling file-extend 
operations are detailed in Table 4-1. This table defines the 
bits in the low-order byte of R2. The high-order 8 bits of 
R2 (Bits 8 through 15) are used in conjunction with the 16 
bits of Rl to define the number of blocks to be added to the 
file (see NOTE 1 below). 


NOTES 


1. The contents of Rl and the high-order 
byte of R2 (Bits 8 through 15) are used 
by FCS in accomplishing the specified 
~-EXTND operation. Thus, 24 bits of 
magnitude are available for specifying 
the number of blocks by which the file 
is to be extended. 


2. If a file previously had space allocated 
to it, a contiguous .EXTND cannot be 
done. You can create a contiguous file 
by opening a new file with a zero 
allocation and then calling .EXTND to 
allocate the desired number of blocks. 
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3. When writing a new file using Queue I/0 
directives, the task must explicitly 
issue .EXTND calls as necessary to 
reserve enough blocks for the file, or 
the file must be initially created with 
enough blocks allocated for the file. 
In addition, the task must put an 
appropriate value in the FDB for the 
end-of-file block number (F.EFBK) before 
closing the file or rewinding and 
reading it. 


4. If R2 contains a zero, FCS defaults to 
noncontiguous allocation. 


To turn off automatic file truncation and close the file, call the 
following routines: 


e .EXTND with Rl and R2 both containing 0 
e CLOSES 


The above procedure is the opposite of a call to .TRNCL. 


4,14 FILE TRUNCATION ROUTINE (.TRNCL) 


The .TRNCL routine truncates a file to its logical end-of-file point, 
deallocates any space beyond this point, and closes the file. 


The following register must be preset before calling this routine: 
RO Must contain the address of the associated FDB. 


The file must have been opened with both write and extend access 
Privileges. Otherwise, the truncation will fail. 


The close operation will be attempted even if the truncation operation 
fails. If errors occur in both operations, the error code from the 
close operation will be returned. 

A call to .TRNCL turns on automatic file truncation. If automatic 
truncation is on, the file is truncated to end-of-file when it is 
closed. If automatic truncation is off, the file is not truncated. 


FCS turns on automatic truncation when it extends a file. A call to 
the .EXTND routine turns off automatic truncation. 


4.15 FILE DELETION ROUTINES 


The .MRKDL and .DLFNB routines are provided for deleting files. 
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NOTE 


If the .MRKDL or .DLFNB routine is’ used 
to delete a file containing sensitive 
information, it is recommended that you 
zero the file before closing it, or 
reformat the disk to destroy the 
sensitive information. (Although the 
file is marked for deletion, the 
information physically remains’ on the 
volume until written over with another 
file, and could be analyzed by 
unauthorized users.) 


4.15.1 .MRKDL - Mark Temporary File for Deletion 


The .MRKDL routine is used in conjunction with a temporary file, that 
is, a file created through the OPNTSW macro call (see Section 3.3). 
Such a file has no associated directory entry. 


A call to the .MRKDL routine is issued prior to closing a temporary 
file, The file so marked is then deleted automatically when the file 
is closed. 


Table 4-1 
R2 Control Bits for .EXTND Routine 


Wowk as iecttes. oF  —..  — _—~—~<~CS~CS;«x 


Value in Low-Order 
Byte of R2 


Meaning 


Indicates that the extend is to be 


noncontiguous. 


200 Indicates that the extend is to be 
noncontiguous. This clears the contiguous 
file attribute. 

201 Indicates that the contiguous area is to be 
added to the file. This clears’ the 
contiguous file attribute. 

203 Indicates that the largest available 
contiguous area is to be added to the file 
if the desired extend space is not 
available. This clears the contiguous file 
attribute. 

205 Indicates that this is the initial extend. 


The file is to be contiguous. 


Indicates that the largest contiguous area 
up to the specified extend size is to be 
added to the file. The file is to be 
contiguous. 


(continued on next page) 
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Table 4-1 (cont.) 
R2 Control Bits for .EXTND Routine 


Value in Low-Order 
Byte of R2 Meaning 


Indicates that the file is to be extended by 
the default extend size for the volume. The 
extend is to be noncontiguous. 


Indicates that the file is to be extended by 
the default extend size for the volume. The 
extend is to be contiguous, whereas the file 
is to be noncontiguous. 


Before calling the .MRKDL routine, you must preset the following 
register: 


RO Must contain the address of the associated FDB. This FDB is 
assumed to contain the file identification, device name, and 
unit information pertaining to the file to be deleted. 


If the .MRKDL routine is invoked while the temporary file is open, as 
is normally done, then the file is deleted unconditionally when it is 
closed. This occurs even if the calling task terminates abnormally 
without closing the file. 


4.15.2 .DLFNB - Delete File by Filename Block 


This routine is used to delete a file by filename block. The .DLFNB 
routine assumes that the filename block is completely filled in; when 
called, it closes the file, if necessary, and then deletes the file. 


Before caiiing this routine, the foliowing register must be preset: 
RO Must contain the address of the associated FDB. 


The .DLFNB routine operates in the same manner as that of the routine 
invoked by the DELETS macro call (see Section 3.18), but .DLFNB does 
not require any of the .PARSE logic and is thus considerably smaller 
(in terms of memory requirements) than the normal DELETS function. 


Like the DELET$ operation, however, if the file to be deleted is not 
currently open, and if an explicit file version number is not present 
in offset location N.FVER of the associated filename block, then the 
-DLFNB operation fails. 
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4.16 DEVICE CONTROL ROUTINE (.CTRL) 
The .CTRL routine is called to perform device-specific control 
functions. The following are examples of .CTRL device-specific 
functions: 

1. Rewind a magnetic tape volume set. 


2. Position to the logical end of a magnetic tape volume set. 


3. Close the current magnetic tape volume and continue file 
operations on the next volume. 


4. Space forward or backward n blocks on a magnetic tape. 


5. Rewind a file on a magnetic tape or a terminal 
(record-oriented device). 


6. Clear terminal end-of-file. 


The following registers must be preset before calling this routine for 
items 1 to 3 above: 


RO Must contain the address of the associated FDB. 
Rl Must contain one of the following function codes: 
e FF.RWD to rewind a magnetic tape volume set 


e FF.POE to position to the logical end of a magnetic 
tape volume set 


e FF.NV to close the current volume and continue file 
operations on the next volume of a magnetic tape 
volume set. 


R2 and R3 must each contain 0. 


When using .CTRL to space forward or backward, you must ensure that 
registers RO, Rl, R2, and R3 contain the following values: 


RO Must contain the address of the associated FDB. 
Rl Must contain the value FF.SPC. 


R2 Must contain the number of blocks to space forward or 
backward. A positive number means space forward; a negative 
number means space backward. 


R3 Must contain 0. 


When using .CTRL to rewind a file, you must ensure that register Rl 
contains the value FF.RWF and that registers R2 and R3 contain 0. 

See Chapter 5 for an explanati 
ons. 


an 
tape device-specific functi 


CHAPTER 5 


FILE STRUCTURES 


IAS and RSX-11 support an identical file structure on disk, DECtape, 
and DECtape MII. They also support ANSI file structure on magnetic 
tape. 


The disk, DECtape, and DECtape II file structure is called FILES-1]1; 
the magnetic tape file structure is ANSI standard. 


5.1 DISK AND DECTAPE FILE STRUCTURE (FILES-11) 


Volumes contain both user files and system files. Disks and DECtapes 
initialized through the INITIALIZE (IAS) or INITVOLUME (RSX) command 
have the standard FILES-11 structure built for them automatically. 
The standard system files created through these commands include the 
Fallaw 


following: 
1. Index file 
2. Storage allocation file 
3. Bad block file 
4. Master File Directory (MFD) 
5. Checkpoint file 


Each FILES-11 volume has a file of each type. A volume may have more 
than one directory file; such files, created by the CREATE/DIRECTORY 
command in IAS, and the UFD command in RSX-1ll systems, are used by the 
system to locate user files on the volume. 


5.1.1 User File Structure 


Your data files on disk and DECtape consist of ordered sets of virtual 
blocks that constitute the virtual structure of the files as they 
appear to you. Virtual blocks can be read and written directly by 
your issuing READS and WRITES macro calls (see Sections 3.15 and 3.16, 
respectively). Virtual blocks are numbered in ascending sequence 
relative to the first block in the file (which is virtual block 1). 
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The virtual blocks of a file are stored on the volume as_ logical 
blocks. The logical block size of all volumes is 256 words; thus, 
each virtual block is also 256 words. When access to a virtual block 
is requested, the virtual block number is mapped into a logical block 
number. The logical block number is then mapped to the _ physical 
address on the associated volume. 


5.1.2 Directory Files 


A directory file contains directory entries. Each entry consists of a 
file name and its associated file number and file sequence number. 
The number of required directory files depends on the number of users 
of the volume. For single-user volumes, only a Master File Directory 
(MFD) is needed; for multiuser volumes, an MFD is required, and one 
User File Directory (UFD) is required for each user of the volume. 


The MFD contains a list of all the UFDsS on the volume, and each UFD 
contains a list of all that user's files. UFDs are identified by User 
Identification Codes (UICsS). A User File Directory is created by the 
UFD command in RSX-11l systems, and by the CREATE/DIRECTORY command in 
IAS. These commands are described in detail in the RSX-11M/M-PLUS MCR 
Operations Manual and the IAS System Management Guide. 


Figures 5-1 and 5-2 illustrate the directory structure for single-user 
and multiuser volumes, respectively. 


5.1.3 Index File 


The index file contains volume information and user file header 
blocks, which are used by the file control primitives (FCP). Because 
the file header blocks (see below) are stored in the index file, they 
can be located quickly. Furthermore, since a file header block is 256 
words in length, it can be read into memory with a single access. 


The index file is created when a volume is initialized for use by the 
host operating system. During initialization, the information 
required by the system is placed in the index file. Appendix E 
contains a detailed description of the format and content of an index 
file. 
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Figure 5-1 Directory Structure for Single-User Volumes 
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Figure 5-2 Directory Structure for Multiuser Volumes 


5.1.4 File Header Block 


Associated with each file is a file header block that contains 
information describing the file. File header blocks are stored in the 
index file. Each file header block is 256 words in length and 
contains three areas: the header area, the identification area, and 
the map area. 


The header area identifies the block as a file header block. Fach 
file is uniquely identified by a file ID consisting of two words. The 
first word of the file ID (that is, the file number) is used _ to 
calculate the virtual block number (VBN) of that file's header block 
in the index file. (This calculation is done as’7 follows: VBN = the 
file number + 2 + the number of index file bit map blocks.) The second 
word (that is, the file sequence number) is used to verify that the 
header block is in fact the header for the desired file. 


When a request to access a file is issued, both the file number’ and 
the file sequence number are specified. The access request is denied 
if the file sequence number does not match the corresponding field in 
the file header block associated with the specified file number. 


When a file is deleted, its file header block is made available for 
subsequently creating a new file, and when the new file is created, a 
different file sequence number is stored in the file header block. If 
you attempt to access a file that has been deleted (for example, by 
referencing an obsolete directory entry), this updated file sequence 
number ensures the failure of the access request, even if the same 
file header block is reused for a different file. 


The identification area specifies the creation name of the file and 
identifies the file owner's’ UIC. This area also specifies the 
creation date and time, the revision number, the date and time of the 
last revision (that is, the time and date on which the last 
modification to the file occurred), and the expiration date. 


The map area provides the information needed by the system to map 
virtual block numbers to logical block numbers. 
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A checksum value is computed each time the file header block is’ read 
from or written to the volume, thus ensuring that the file header 
block is transferred correctly. Appendix F contains a detailed 
description of the format and content of the file header block. 


5.2 MAGNETIC TAPE FILE PROCESSING 


IAS and RSX-11 support the standard ANSI magnetic tape structure as 
described in "Magnetic Tape Labels and File Structure for Information 
Interchange," ANSI xX3.27-1978. Any of the following file/volume 
combinations can be used: 


e Single file on a single volume 

e Single file on more than one volume 

e Multiple files on a single volume 

e Multiple files on more than one volume 
Items 2 and 4 above constitute a volume set. 


The record format on magtape is different from that on disk. When a 
File that contains variable-length records or fixed-length records 
that cross block boundaries is copied to magtape, it occupies more 
blocks on the magtape than it did on the disk. This is so because on 
Magtape the record counts are larger than on disk, and there is unused 
space at the end of the _ blocks. In addition, the cannot-cross- 
block-boundaries bit is set in the file's FDB. 


The sequence in which volume and file labels are used and the format 
of each label type is defined in Appendix G. 


NOTE 


There is no place for the creation time 
or tne length of the file in an ANSI 
file header label. Consequently, the 
creation time of a file on ANSI magtape 
is listed as 0. If a contiguous file is 
copied to ANSI magtape and then 
transferred back to disk, the resulting 
disk file is not marked contiguous even 
if the /CO switch is used, because’ the 
system cannot know how much space to 
allocate for the output file when it 
reads from magtape. 


5.2.1 Access to Magnetic Tape Volumes 


Magnetic tape is a sequential access, single-directory storage medium. 
Only one user can have access to a given volume set at a time. No 
more than one file in a volume set can be open at a time. Access 
protection is performed on a volume set basis. On volumes produced by 
DIGITAL systems, user access rights are determined by the contents of 
the owner identification field as described in Section G.1.1.1. 
Volumes produced by non-DIGITAL systems are restricted to read-only 
access unless explicitly overridden at MOUNT time. 
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5.2.2 Rewinding Volume Sets 


You can rewind a magnetic tape volume set either by using the FDOPSR 
macro call before an OPENS or CLOSES or by using the .CTRL file 
control subroutine. Regardless of the method used to rewind the 
volume set, the following procedures are performed by the file control 
system: 


1. All mounted volumes are rewound to BOT. 


2. If the first volume in the set is not mounted, the unit to be 
used is placed off line. 


3. If the volume is not already mounted and if the rewind was 
requested by an OPENS macro call or by a .CTRL call, a 
request to mount the first volume is. printed on the 
operator's console. 


4. If the rewind was requested on a CLOSES macro call, no mount 
message is issued until the next volume is needed. 


5.2.3 Positioning to the Next File Position 


The normal procedure for writing a new file onto a magnetic tape is to 
begin writing the file following the end of the last file currently in 
the volume set. However, the FDOPSR macro call can be used _ to 
indicate that the new file is to be written immediately after the 
end-of-file labels of the most recently closed file. This next file 
DoSition option causes the loss ci any files physically following: this 
most recently closed file in the volume set. 


i 
h 
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If, in addition to the next file position option, the rewind option 
also is specified, the file is created after the VOL1 label on the 
first volume of the set. All files previously contained in the entire 
volume set are lost. 


To create a file in the next file position, FA.POS must be set in FDB 
location F.ACTL. The default value for this FDB position is 0 (not 
FA.POS). The default indicates that the file system is to position at 
the logical end of the volume set to create the file. 


When the default is used, no check is made for the existence of a file 
with the same name in the volume set. Therefore, a program written to 
use magnetic tape normally should specify FA.POS. 

The next file position option is ignored by directory device file 
processors. However, programs written mainly for directory devices 
can specify the next file position option in open commands for output 


and, therefore, override the position-to-end process normally used 
automatically when used with ANSI magtape. 


5.2.4 Single-File Operations 
Single-file operations are performed by specifying the rewind option 
before the open and before the close. Using this approach, you can 
perform scratch tape operations as follows: 

1. Open the first file with rewind specified. 


2. Write the data records and close the file with rewind. 


3. Open the first file again for input (rewind is optional). 


Saar) 
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4. Read and process the data. 

5. Close the file with rewind. 

6. Open the second file with rewind specified. 
7. Write the data records. 


8. Close the file with rewind and perform any additional 
processing. 


5.2.5 Multiple-File Operations 

A multiple-file volume is created by opening, writing, and _ then 
closing a series of files without specifying a rewind. The sequential 
processing of files on the volume can be accomplished by closing 
without rewind and then opening the next file without rewind. 


Opening a file for extend (OPENSA) is legal only for the last file on 
the volume set. 


The following tape operations are performed to create a multiple-file 
tape volume: 


l. Open a file for output with rewind. 
2. Write data records and close the file. 
3. Open the next file with no rewind. 
4. Write the data records and close the file. 
5. Repeat for as many files as desired. 
Files on tape can be opened in a nonsequential order, but increased 


processing and tape-positioning time is required. Nonsequential 
access of files in a multivolume set is not recommended. 


5.2.6 Using .CTRL 


The .CTRL file control routine can be called to override normal FCS 
defaults for magnetic tape. Examples of its uses are: 


1. Continuing processing a file on the next volume of a _ volume 
set before the end of the current volume is reached. 


2. Positioning to the logical end-of-volume set. 

3. Rewinding a volume at other than file open or close. 

4. Spacing forward or backward n records. 

5. Rewinding a file. 
When .CTRL is used to continue processing a file on the next volume, 
the first file section on the next volume is opened. File sections 
occur when a file is written on more than one volume. The portion of 
the file on each of the volumes constitutes a file section. For input 
files, the following .CTRL processing occurs: 

1. If the current volume is the last volume in the set (that is, 


there is no next volume), end-of-file is reported to you. 
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2. If another file section exists, the current volume is rewound 
and the next volume is mounted. A request to the operator is 
printed, if necessary. 


3. The header label (HDR1) of the next file section is read and 
checked. 


4. If all required fields check, the operation continues. 


5. If any check fails, the operator is requested to mount’ the 
correct volume. 


For output files, the following processing occurs: 


1. The current file section is closed with EFOV1 and EOV2 labels 
and the volume is rewound. 


2. The next volume is mounted. 

3. A file with the same name and the next higher section number 
is opened for write. The file set identifier is identical 
with the volume identifier of the first volume in the volume 
set. 

NOTE 
I/O buffers that are currently in memory are written 


on the next file section. 


When .CTRL is usSed to position to the logical end-of-volume set, the 
file system positions between the two tape marks at the logical end of 
the last volume in the set. 


When .CTRL is used to space forward or backward across blocks on 
magnetic tape, spacing crosses volumes for multivolume files. 


5.2.7 Examples of Magnetic Tape Processing 
The following pages contain examples of FCS statements used to process 
magnetic tape. Macro parameters not related to magnetic tape handling 


have been omitted from the statements so that you need consider only 
those matters directly related to magnetic tape. 


5.2.7.1 Examples of OPENSW to Create a New File - All routines expect 
RO to contain the FDB address. 


OPRWDO: 


OPEN WITH REWIND 


~e ™e NO 


FDOPSR- RO,,,,,#FA.ENB! FA. RWD 7;SET REWIND AND ENABLE USE 
BR OPNOUT ;OF F.ACTL 
OPNXTO: 


OPEN FOR NEXT FILE POSITION 


we NO NO 


FDOPSR' RO,,,,,#FA.ENB! FA.POS ;SET POSITION TO NEXT 
BR OPNOUT ;AND ENABLE USE OF F.ACTL 
OPROYK: 


a 


FILE STRUCTURES 


ACCESS CONTROL BITS 


me te TGS 


BIC #FA.ENB,F.ACTL (RO) 
BR OPNOUT 
OPROVO: 


USER ACCESS CONTROL BITS 
FDOPSR RO,-7747,#0 
BR OPNOUT 


me me Me 


e me MO 


‘ 
OPOURO: 

BIS #FA.ENB,F.ACTL (RO) 
OPNOUT: FDBFS$R RO,,#2048. 

OPENSW RO 

RETURN 


Sele lee 
contain the FDB address. 


OPRWDI: 


OPEN WITH REWIND 


i iT 


FDOPSR' RO,,,,,#FA.ENB! FA.RWD 
BR OPNIN 
OPCURI: 


ACCESS CONTROL BITS 


=e Me NO MO 


BIC #FA.ENB,F.ACTL(RO) 
BR OPNIN 


QOPEN USING USER ACCESS CONTRO 


wes ee ee Se ee ee ee ~~ wee eee 


oe se Me 


F 
OPDFLI: BIS #FA.ENB,F.ACTL(RO) 


OPNIN: FDBFSR_ RO,,#2048. 
OPENSR- RO 
RETURN 
5.2.7.3 Examples of CLOSES - All routines expect RO to 


FDB address. 


CLSCUR: 


USER ACCESS CONTROL BITS 


me Be Me Te 


BIC #FA.ENB,F.ACTL(RO) 
BR CLOSE 


CLSRWD: 


; CLOSE REWINDING THE VOLUME 

; 
FDOPSR' RO,,,,,#FA.ENB! FA.RWD 
BR CLOSE 


=e 


Examples of OPENSR to Read a File - 


OPEN FILE AT END OF VOLUME KEEPING CURRENT USER 


;DISABLE USE OF F.ACTL 


OPEN FILE AT END OF VOLUME - SELECT SYSTEM DEFAULT FOR 


;DISABLE USE OF AND RESET 
;F.ACTL TO ZERO 


OPEN FILE WITH CURRENT USER ACCESS CONTROL 


;ENABLE USE OF F.ACTL 
;OVERRIDE BLOCK SIZE FOR TAPE 


All routines expect RO to 


OPEN STARTING SEARCH AT CURRENT TAPE POSITION KEEPING USER 


;DISABLE USE OF F.ACTL 


;ENABLE USE OF F.ACTL 
;OVERRIDE BLOCK SIZE FOR TAPE 


contain the 


CLOSE LEAVING TAPE AT CURRENT POSITION AND KEEPING 


;DISABLE USE OF F.ACTL 
;DEFAULT IS LEAVING AT CURRENT 
; POSITION 


;SET REWIND AND ENABLE USE OF 
;F.ACTL 


FILE STRUCTURES 


CLOSE WITH USER ACCESS CONTROL BITS 


¢ ‘~e 


1 
CLSDFL: BIS #FA.ENB,F.ACTL(RO) ; ENABLE USE OF F.ACTL 
CLOSE: CLOSES RO 

RETURN 


5.2.7.4 Combined Examples of OPENS and CLOSES for Magnetic Tape - The 
following examples call routines in previous examples. By combining 
various magnetic tape operations, you can process tape volumes in the 
following ways. 


’ 

; SCRATCH TAPE OPERATIONS--SINGLE FILE VOLUME-- 

a 

SCROUT: MOV #FDBOUT, RO ;SELECT FDB AND OPEN 
CALL OPRWDO ;OUTPUT FILE WITH REWIND 
RETURN 

SCRIN: MOV #FDBIN,RO ;SELECT FDB AND OPEN FOR 
CALL OPRWDI ; INPUT WITH REWIND 
RETURN 

CLSCRO: MOV #FDBOUT,RO ;CLOSE SCRATCH FILE 
BR CLSVOL ;REWINDING VOLUME 

CLSCRI: MOV FDBIN,RO 

CLSVOL: CALL CLSRWD 
RETURN 


MULTI-FILE VOLUME OPERATIONS 
PNXTI: 


OPEN FILE FOR READING WHEN FILE IS NEXT OR FURTHER UP THE VOLUME 


me we Me Cte Ne Me 


MOV #FDBIN,RO ;SELECT FDB 
CALL OPCURI ;OPEN FILE 
RETURN 


OPENIN: 


OPEN FILE FOR READING WHEN POSITIONED PAST IT 


me Me NO 


MOV #FDBIN,RO ;SELECT FDB 
CALL OPRWDI 
RETURN 


MULTI-FILE OUTPUT OPERATIONS 


PNINT: 


START NEW VOLUME DESTROYING ALL PAST FILES ON IT 


me te Me Cwe te Me 


MOV #FDBOUT, RO ;SELECT OUTPUT FDB 
CALL OPRWDO ;OPEN WITH REWIND 
RETURN 


OPNEXT: 


OPEN OUTPUT FILE AT NEXT FILE POSITION DESTROYING ANY FILE 
THAT MAY BE AT OR PAST THAT POSITION 


me “™e “se MO 


MOV #FDBOUT, RO ;SELECT OUTPUT FDB 
CALL OPNXTO 
RETURN 


OPENDT: 


’ 


Shae) 


FILE STRUCTURES 


OPEN OUTPUT FILE AT CURRENT END OF VOLUME SET 
ACCESS CONTROL BITS 


me te Se 


MOV #FDBOUT, RO ;SELECT 
CALL OPROVK 
RETURN 


OPNEOV: 


OPEN OUTPUT FILE AT CURRENT END OF VOLUME AND 
ACCESS CONTROL 


me ™6 “OO Ge 


MOV #FDBOUT,RO ; SELECT 
CALL OPROVO 
RETURN 
; 
; NOT LAST FILE IN FILE SET CLOSE ROUTINE 
CLSFLO: MOV #FDBOUT, RO ; SELECT 
BR CLSXX 
CLSFLI: MOV #FDBIN,RO ;SELECT 
CLSXX: CALL CLSCUR 
RETURN 


TO APPEND TO LAST FILE 


=e "Oe MO 


OPENSA #FDBOUT 


S710 


KEEPING USER 


OUTPUT FDB 


MAKE THAT THE USER 


OUTPUT FDB 


OUTPUT FDB 


INPUT FDB 
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As noted in Section 2.4.3, a collection of routines available from the 
system object library ([1,1]SYSLIB.OLB) may be linked with your 
program to provide all the logical capabilites required to process 
command lines dynamically. These system facilities include the 
following routines: 


1. Get Command Line (GCML). This routine accomplishes all the 
logical functions associated with the entry of command lines 
from a terminal, an indirect command file, or an on-line 
storage medium. Using GCML relieves you of the burden of 
manually coding command line input operations. 


2. Command String Interpreter (CSI). Normally, this routine 
takes command lines from the GCML command line input buffer 
and parses them into the appropriate dataset descriptors 
required by FCS for opening files. 


This body of routines is linked with your program at task-build time. 
GCML and CSI are often jointly incorporated in system or application 
programs as a standardized interface for obtaining and interpreting 
dynamic command line input. The flow of data during command line 
processing is shown in Figure 6-l. 


Although these routines are presented in the context of being used 
together for processing command line input, each may be used 
independently of the other. Doing so, however, means that you must 
manually code the functions otherwise performed by the missing 
component. The joint use of these routines is assumed throughout this 
chapter to be the "normal" situation. 


Invoking GCML and CSI functions requires that certain initialization 
operations be accomplished at assembly time. This initialization sets 
up the GCML command line input buffer, defines and initializes control 
blocks for both GCML and CSI, and establishes the necessary working 
storage and communication areas for thesSe_ routines. Also, the 
appropriate macro calls that invoke GCML and CSI execution-time 
functions must be included in the source coding at desired logical 
points to effect the dynamic processing of command lines. 


GCML and CSI macro calis observe the same register conventions 
applicable to FCS. All registers except RO are preserved exactly as 
in all FCS macro calls. RO is used to contain the address of the GCML 
control block or the CSI control block, as appropriate. 


As with all FCS macro calls, the GCML and CSI macro calls must also be 
listed as an argument in an .MCALL directive (see Section 2.1) before 
being issued in your program. 
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Figure 6-1 Data Flow During Command Line Processing 


6.1 GET COMMAND LINE (GCML) 


The Get Command Line (GCML) routine embodies all_ the logical 
capabilities required to enter command lines dynamically during 
program execution. GCML accepts input from a terminal or an indirect 
command file that contains predefined command lines. If your program 
allocates sufficient buffer space in the file storage region (see 
Section 2.6), GCML accepts commands that are longer than one line of 
terminal input. The continuation of commands from one line to the 
next is effected when a hyphen appears as the last printing character 
of a command line. 
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All GCML functions require you to create and initialize a GCML control 
block. The macro call that accomplishes this function is described in 


detail in the following section. The GCML run-time macro calls 
may be issued dynamically are described in Section 6.1.3. 


6.1.1 GCMLBS - Allocate and Initialize GCML Control Biock 


Issuing the GCMLBS$ macro call accomplishes the following assembly- 


functions: 


e Reserves storage for, and initializes a GCML control 
within, your program. 


e Creates and initializes an FDB in the first part of the 
control block. This FDB is used to open a command file. 


that 


time 


block 


GCML 


Such 


a file, which may employ a terminal or a file-structured 
device such as a disk, is opened and read by your program in 


the same manner as any other file. Initializing 


and 


maintaining this FDB, however, is under GCML and FCS control 


and need not be of concern to you. 


e Creates and initializes a default filename block within 


fala aa ee ee ee | 


the 


GCML control biock. This default filename block pertains to 
an indirect command file. If you do not specify an explicit 
file name string for an indirect command file, the values CMI 
for the file name and .CMD for the file type are assumed by 
default. There is no default designation for the device name. 


e Defines the symbolic offsets for the GCML control block 


and 


initializes certain offsets to required values. These offsets 


are described in detail in Section 6.1.2. 
The GCMLBS macro call is specified in the following format: 


label: GCMLBS maxd,prmpt,ubuf,lun,pdl,size 


label 
A symbol that names the GCML control block and defines 
address. This label permits the GCML control block 
referenced directly by all the GCML run-time routines 
require access to this structure (see Section 6.1.3). 


maxd 


A numeric value that specifies the maximum nesting 


its 


to be 


that 


depth 


permitted for indirect command files. This parameter determines 


the number of nested indirect command files that GCML will 


allowed to access in obtaining command line input. 


be 


An indirect command file, which often resides on disk, contains 


well-defined, nonvarying command sequences, which may be 


read 


directly by GCML to control operations that are highly repetitive 
(such as Task Builder activities). Significant advantages in 


terms of convenience and faster execution result from using 


indirect command file. 


an 


prmpt 


ubuf 


lun 


pdl 
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If this parameter is not specified, a nesting level depth of 0 is 
defined by default, effectively eliminating an indirect command 
file as a source of command line input. 


A user-specified, 3-character ASCII prompting sequence. This 
parameter constitutes a default prompt string that is typed out 
by GCML to your terminal to solicit command line input. 


The ASCII prompting sequence is formulated into the following 
6-byte string: 


1. A carriage return (<CR>) and a line-feed (<LF>) 
2. The three ASCII characters that you specify 
3. A right angle bracket (>) 


The above string initializes GCML control block offset location 
G.DPRM (See Section 6.1.2). 


If this parameter is not specified, the right angle bracket (>), 
preceded by three blanks, is defined by default for use by GCML 
as the default prompting sequence. 


The address of a buffer to be used by GCML for temporary storage 
of command line input. If this parameter is not specified, a 
buffer, whose length is determined by the size parameter, is 
reserved in the GCML control block for command line input. If 
neither this parameter nor the size parameter is specified, a 
41-word buffer is reserved by default in the GCML control block. 


A logical unit number. The device assigned to this logical unit 
number is used by GCML as the command input device. If this 
parameter is not specified, a logical unit number of 1 is used by 
default. 


The address of an area reserved in your program for use aS a 
push-down list. This area is reserved as working storage for use 
in connection with indirect command files. 


Normally, the pdl parameter is not specified; in this case, 
sufficient storage for the push-down list is added to the control 
block by default in accordance with the algorithm described 
below. 


size 
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The push-down list is created through statements logically 
equivalent to the following: 


- EVEN 
label: .BLKB G.LPDL 


The user-supplied label specifies the push-down list and defines 
its address; G.LPDL, which is defined by the GCMLBS macro, is 
the length (in bytes) of the push-down list. 


The length of the push-down list is a function of the maximum 
number of nested indirect command files that may be accessed by 
GCML in obtaining command line input. The value of G.LPDL is 
calculated according to the following algorithm: 


1. Add 1 to the maximum nesting level depth declared with the 
maxd parameter (see above). 


2. Multiply the sum of step 1 by 16(decimal), the appropriate 
number of bytes that must be reserved for the push-down list. 


For example, if the maxd parameter is specified as 4, the length 
of the push-down list is determined as follows: 


(44+1)*16. = 80. bytes 


From the above, note that 16(decimal) bytes of storage are 
required for each indirect command file, plus a total of 
16(decimal) bytes for use as general overhead. 


The size, in bytes, of the buffer reserved for command line 
input. The specified size must always include two extra bytes 
that are used internally by GCML. The default value for size is 
82 (that is, 80 bytes for command line input and 2 bytes GCML 
overhead). 


If you want GCML to accept continuation lines, the specified 
value for the size parameter must be greater than 82. When the 
size is greater than 82, the bit value GE.CON is set in the 
status and mode control byte (offset G.MODE) of the GCML command 
block. This value indicates that the continuation mechanism is 
in effect. 


The following examples represent a GCMLBS macro call as it might 
appear in your program: 


GCLBLK: GCMLBS$ 4.,GCM,BUFADR,1. 
GCLBLK: GCMLB$ ,,BUFADR 
GCLBLK: GCMLBS$ DEPTH,GCM,BUFADR,CMILUN, PDLIST,BUFSIZ 
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6.1.2 GCMLDS ~- Define GCML Control Block Offsets and Bit Values 


The GCMLDS macro, which is invoked automatically by the GCMLBS$ 
macro call, locally defines the GCML control block offsets and 
bit values within the current module. These offsets and 
associated bit values are listed and described below. 


Offset 
Name Functional Significance 
G.ERR Error Return Code Byte. This field initially 


contains 0. If any one of the error conditions 
recognized by GCML occurs during the processing of 
a command line, an appropriate error code is 
returned to offset location G.ERR in the control 
block. These error codes are described below: 


GE.IOR! - Indicates that an I/O error occurred 
during the input of a command line. 

GE.OPR! - Indicates that GCML was unable to 
open or reopen the specified command file. 
GE.BIF - Indicates that a syntax error was 
detected in the name of the indirect command 
file. 

GE.MDE - Indicates that an attempt was made to 
exceed the maximum permissible nesting-ievel 


depth for an indirect command file (see the 
maxd parameter in the GCMLBS macro call above). 


GE.RBG - Indicates that the command line input 
buffer was too small for the total command. 
This condition can occur when multiple lines 
have been entered uSing the continuation 
mechanism. The input buffer contains as _ much 
of the command as possible. 


GE.EOF - Indicates that the end-of-file (EOF) 
on the first (unnested) command file was 
detected. 


This code is set in connection with command file 
input. When the first call is issued for input, 
GCML attempts to retrieve an MCR/PDS command line. 
The first line obtained, whether it is an MCR/PDS 
command or a terminal command, is accomplished at 
command level 0. If the name of an indirect 
command file is then entered, the command input 
level is incremented to 1. Each indirect file 
name entry thereafter increments the command input 
level. When the end-of-file (EOF) is encountered 
on any given indirect file, the command input 
level is decremented by 1, restoring the count to 
the previous level and reopening the associated 
command file. The next command line from that 
file is then read. 


1. For GE.IOR and GE.OPR, additional information concerning the error 
is available by examining the FCS error code at offset F.ERR from the 
start of the GCML block. 


Offset 
Name 


G.MODE 


COMMAND LINE PROCESSING 


Functional Significance 


If an MCR/PDS command has already been read at 
level 0, entering another MCR/PDS command when 
level 0 is again reached causes the error code 
GE.EOF to he returned to offset location F.ERR of 
the GCML control block. Hence, only one MCR/PDS 
command line can be read at level 0. If input 
thus fails at MCR/PDS level 0, then GCML continues 
to prompt for input until you type CTRL/Z to 
indicate terminal end-of-file (EOF). 


In summary, the first line of input is always read 
at level 0. This initial input may be an MCR/PDS 
command; if the MCR/PDS command fails or is null, 
the command input file (normally a terminal) is 
then opened at level 0. Multiple inputs at level 
0 are permissible only in the latter case, that 
is, from the command input file. 


Status and Mode Control Byte. This field is 
initialized at assembly time with bit definitions 
to specify certain default actions for GCML during 
the retrieval of a command line. At run time, you 
can reset default status and mode control bits, if 
desired, by issuing a Bit Clear Byte (BICB) 
instruction that takes as the source operand the 
symbolic name of the bit to be cleared. In the 
case of the GE.LC value (See below), th 


: 
Inetriction can ha mead tn nvarr 
wwe mI Ne NA ho NS ww we hk 


bai eb Uvuesvil we Heed u 


action. 


The symbolic names of the bits defined in the 
status and mode control byte are as follows: 


GE.IND - (Default) Indicates that a command 
line containing a leading at sign (@) is to be 
treated as an explicit indirect command file 
specifier. If, for any reason, you reset this 
bit to 0, a command line containing a leading 
at sign (@) is returned to the calling program. 


GE.CLO - (Default) Indicates that the command 
file currently being read is to be closed after 
each issuance of the GCMLS macro call. If you 
reset this bit to 0 for any reason, GCML keeps 
the current command file open between calls for 
input. In this case, the FSR (see Section 
2.661) must include one additional 
512 (decimal) -byte buffer for command line 
input. This requirement adds to the total FSR 
block buffer space normally reserved for the 
maximum number of files that may be open 
simultaneously for record I/O processing. 


Clearing the GE.CLO bit in the status and mode 
control byte effectively renders 512(decimal) 
bytes of FSR block buffer space unavailable for 
other purposes, Since the command file remains 
open between calls for command line input. 


Offset 
Name 


G.PSDS 


G.CMLD 
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Functional Significance 


GE.COM - (Default) Indicates that a command line 
having a leading semicolon (;) is to be treated as 
a comment. Such lines are not returned to the 
calling program. If, for any reason, you reset 
this bit to 0, a command line containing a leading 
semicolon (;) is returned to the calling program. 


GE.CON —- Indicates that the continuation 
mechanism is in effect. This is the default if 
the value of the size parameter of the GCMLBS 
macro is greater than 82. You must not attempt to 
set this value in the mode byte without providing 
a buffer larger than 82 bytes. 


GE.LC - Indicates that lowercase characters in 
the command line are to be passed to your program 
without mapping. Unless you explicitly set this 
value in the GCML control block at run time, the 
default action will be to map lower- and uppercase 
characters to uppercase before transmission to 
your program. 


Prompt String Descriptor. This 2-word field is 
initialized to 0O at assembly time through the 
GCMLBS$ macro call (see Section 6.1.1). 


When the GCMLS macro call is issued to request 
command line input (see Section 6.1.3.1), the 
address and the length of a prompting sequence is 
usually not specified. In this case, the prompt 


string descriptor words in the GCML control block 


are cleared, causing GCML to tyne out the default 


prompt string contained in offset location G.DPRM 
(see below) to solicit command line input. 


If you wish to define an alternate prompt’ string 
elsewhere in the program, you may do so through 
the .ASCII directive. The address and length of 
this alternate prompt string may then be specified 
as the adpr and Inpr parameters in subsequent 
GCML$ macro calls. These parameters cause offset 
locations G.PSDS+2 and G.PSDS to be initialized 
with the address and the length, respectively, of 
the alternate prompt string. The alternate prompt 
String is then typed out by GCML to solicit 
command line input, thereby overriding the default 
prompt string previously established through the 
GCMLB$ macro call (see G.DPRM below). 


If the adpr and Inpr parameters are not’ specified 
in a subsequent GCML$ macro call, offset location 
G.PSDS in the control block is automatically reset 
to 0, causing GCML to revert to the use of the 
default prompt string contained in offset location 
G.DPRM. 


Command Line Descriptor. This 2-word field is 


initialized by GCML after retrieving a command 
line. The address of the line just obtained is 
returned to offset location G.CMLD+2, and the 
length (in bytes) of the command line is’ returned 
to offset location G.CMLD. 
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offset 

Name Functional Significance 
The contents of these word locations in the GCML 
control block may be passed to CSI as the "buff" 
and "len" parameters in the CSI$1 macro call (see 
Section Os 2ede Lys The combination of these 
parameters constitutes the command line 
descriptors that enable CSI to retrieve file 
specifiers from the GCML command line input 
buffer. 

G.ISIZ Impure Area Size Indicator. This symbol is 
defined at assembly time, indicating the size of 
an impure area within the GCML control block to be 
used as working storage for pointers, flags, 
counters, and so forth, in connection with input 
from an indirect command file. In normal usage, 
you need not be concerned with this symbol. 
The space between the FDB and the default prompt 
string (see G.DPRM below) constitutes the impure 
area of the GCML control block. The size the 
FDB is defined by the value of the symbol S.FDB. 
Thus, the size of the impure area is equal _ to 
G.DPRM-S.FDB. 

G.DPRM Default Prompt String. This 6-byte field is 


initialized at assembly time 


with 


prompt string created through the prmpt 
of the GCMLBS macro call (see Section 6.1.1). In 
the absence of the adpr and lnpr parameters in the 


GCML$ macro call (see Section 


default prompt string is typed 
solicit terminal input. 


out 


6.301) 4 
by GCML to 


You can reference the GCML control block offsets and bit 
another module by establishing the appropriate symbolic definitions 
within that module through one of the following statements: 


GCMLD$ ;DEFAULT LOCAL DEFINITION. 
GCMLD$ DEFSL ;LOCAL DEFINITION. 
GCMLD$ DEFSG ;GLOBAL DEFINITION. 


6.1.3 GCML Run-Time Macro Calls 


Three run-time macro calls are provided in GCML to perform 
functions, as described below: 

GCMLS - To retrieve a command line 

RCMLS - To reset the indirect command file scan to 


(unnested) level 


CCMLS - To close the current command file 


the default 


parameter 


this 


values in 


specific 


the 


first 


These routines are described separately in the following sections. 
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6.1.3.1 GCMLS - Get Command Line - The GCMLS macro call serves as 


your 


program interface for retrieving command lines from a terminal or 


an indirect command file. This macro call can be issued at any 
logical point in the program to solicit command line input. 


This macro call takes the following format: 
GCML$ gclblk,adpr,inpr 

gclblk 
The address of the GCML control block. This symbol must be the 
same as that specified at assembly time in the label field of the 
GCMLB$ macro call (see Section 6.1.1). If this parameter is not 
specified, RO iS assumed to contain the address of the GCML 
control block. 

adpr 
The address of your program location containing an alternate 
prompt string. When this optional parameter and the inpr 
parameter below are present in the GCML$ macro call, the 
alternate prompt string is typed out on your terminal to solicit 
command line input. The normal default prompt string, as 
contained in offset location G.DPRM of the GCML control block 
(see Section 6.1.2), is thereby overridden. 

lnpr 


The length (in bytes) of the alternate prompt string. This 
parameter is also optional; if not specified, offset location 
G.PSDS in the GCML control block (see Section 6.1.2) is cleared. 


If this parameter is specified but the adpr parameter above is 
not, an .ERROR directive is generated during assembly that causes 
the error message PROMPT STRING MISSING to be printed in the 
assembly listing. This message is a diagnostic announcement of 
an incomplete prompt string descriptor in the GCML$ macro call. 
If this parameter is not given but the adpr parameter above is 
given, the default prompt string is used. 


If the adpr and IlInpr parameters are not specified in a _ subsequent 


GCML$ 


macro call, offset location G.PSDS in the GCML control block is 


automatically reset to 0, causing GCML to revert to using the default 
prompt string contained in offset location G.DPRM (see Section 6.1.2 
above). 


When 


the GCML$ macro call is issued, the following actions occur: 


1. RO is loaded with the address of the GCML control block. hi 
the gclblk parameter is not specified, as described above, RO 
is assumed to contain the address of the GCML control block. 
If it does not, RO must first be initialized manually with 
the address of the control block before the GCMLS$ macro call 
is issued. 


2. The address and the length of the alternate prompt string, if 
specified, are stored in control block offset locations 
G.PSDS+2 and G.PSDS, respectively. These two words 
constitute the alternate prompt string descriptor. 
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3. Code is generated that calls GCML to transfer a command line 
to the command line input buffer. If the last character of 
an input line is a hyphen, and if the value GE.CON is present 
in the status and mode control byte, GCML will automatically 
transfer commands that run to more than one line. The 
continuation lines obtained are concatenated in the input 
buffer with the continuation hyphen(s) removed. 


At the initial issuance of the GCML$ macro call, an attempt is made to 
retrieve an MCR/PDS command line. If this attempt fails, or if the 
MCR/PDS command line is null, the FDB within the GCML control block is 
used to open a file for command line input. If the command input 
device is a terminal, a prompt string is typed out to solicit input. 
Any desired command input may then be entered. If the continuation 
mechanism is being used, the prompt string is similarly typed to 
solicit subsequent portions of a continued command line. 


If appropriate, you may enter an at sign (@) as the first character in 
the command line, followed by the name of an indirect command file. 
This file name identifies an explicit indirect command file from which 
input is to be read. GCML then opens this file and retrieves the 
first command line therein. On successive GCML calls, this file is 
read until one of the following occurs: 

1. The end-of-file (EOF) is detected on the current indirect 
file. In this case, the current indirect file is closed, the 
command input level count is decremented by 1, and _ the 
previous command file is reopened. If the command input 
level count is already 0 when EOF is detected, the error code 
GE.EOF is returned to offset location G.ERR of the GCML 
control block (see Section 6.1.2). 


2. An indirect file specifier is encountered in a command line. 
In this case, the current indirect command file is closed (if 
not already closed), and the new indirect file is opened. 
The first command line therein is then read. 


3. An RCMLS macro call is issued in the program (see Section 
6.1.3.2 below). In this case, the current indirect command 
file is closed, and the command input count reverts to level 
0; that is, the top level command file is again used for 
input. 


You may also enter a Semicolon (;) as the first character in the 
command line. If GE.COM is set, such a line is treated aS a comment 
and is not returned to the calling program. If GE.COM is clear, the 
line is returned to the calling program. 


Whether a command line is entered manually or retrieved from an 
indirect command file, the address and the length of the command line 
thus obtained are returned to GCML control block offset locations 
G.CMLD+2 and G.CMLD, respectively. Together, these two words 
constitute the command line descriptors. These descriptors may be 
specified as the "buff" and "len" parameters in the CSIS$1 macro call 
(see Section 6.2.3.1). 


Successful retrieval of a command line causes the C-bit in the 
Processor Status Word to be cleared. Any error condition that occurs 
during the retrieval of a command line, however, causes the C-bit to 
be set. In addition, a negative error code is returned to offset 
location G.ERR of the GCML control block. These error codes are 
described in detail in Section 6.1.2 above. 
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Examples of the GCMLS macro call follow: 
GCMLS #GCLBLK 
GCMLS 
GCML$ #GCLBLK, #ADPR, #LNPR 


The first example specifies the symbolic address of the GCML control 
block. The second example assumes that RO contains the address of the 
GCML control block. Both these forms of the GCML$ macro call employ 
the default prompt string contained in offset location G.DPRM of the 
control block to solicit command line input. The last example 
specifies the address and the length of an alternate prompt string 
that you have defined within the program. This alternate prompt 
string is used by GCML to prompt for terminal input, rather than the 
default prompt string contained in the GCML control block. 


6.1.3.2 RCMLS$ - Reset Indirect Command File Scan - If you must close 
the current indirect command file and return to the top-level file, 
that is, to the first (unnested) file, he or she may do so by issuing 
the RCMLS macro call. 


The RCML$ macro call is specified in the following format: 


RCMLS gclblk 


gclblk 


The address of the GCML control block. If this parameter is not 
specified, RO is assumed to contain the address of the GCML 
control block. 


When this macro call is issued, the current indirect command file is 
closed, returning control to the top-level (unnested) file. A 
subsequent GCMLS$ macro call then retrieves the next command line from 
the O-leveil command file. Note, however, that a second MCR/PDS 
command at level 0 cannot be read (see GE.EOF error code in offset 
location G.ERR of GCML control block, Section 6.1.2). 


Examples of the RCMLS$ macro call follow: 
RCMLS #GCLBLK 
RCMLS RO 


This macro call requires only the address of the GCML control block. 


6.1.3.3 CCML$ - Close Current Command File - It is often desirable to 
close the current command file between calls for input in order to 
free FSR block buffer space for some other use. The command file is 
closed automatically after the retrieval of a command line, provided 
that the GE.CLO bit in the status and mode control byte remains 
appropriately initialized (see Section 6.1.2). This bit is set to 1 
at assembly time. If you reset this bit to 0, the current command 
file remains open between calls for input. 
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For a program that frequently reads command files, this may be a 
desirable operational mode, since keeping the file open between calls 
for input reduces total file access time. However, should it be 
desirable to close such a file to free FSR block buffer space, you may 
do so by issuing the CCMLS macro call. 


The CCMLS$ macro call takes the following format: 


CCML$  gclblk 


gclblk 


The address of the GCML control block. If this parameter is not 
specified, RO is assumed to contain the address of the GCML 
control block. 


Issuing this statement closes the current command file, effectively 
releasing 512(decimal) bytes of FSR block buffer space for some other 
use between calls for input. If the command file is already closed 
when the CCMLS macro call is issued, control is merely returned to the 
calling program. A subsequent GCMLS macro call then causes the 
command file to be reopened and the next command line in the file to 
be returned to the calling program. 


Examples of this macro call are shown below: 
CCMLS$ #GCLBLK 
CCMLS RO 


As in the RCMLS macro call above, this macro call takes a single 
parameter, namely, the address of the GCML control block. 


6.1.4 GCML Usage Considerations 


As noted in Section 6.1.1, the GCMLBS macro call creates an FDB in the 
first part of the GCML control block. Although ordinarily you need 
not manipulate this FDB (since it is under GCML and FCS control), you 
can perform the following operations on this FDB: 


1. In an irrecoverable error situation, you can issue a CLOSES 
macro call (see Section 3.8) in connection with this FDB 
before issuing the system EXITS macro call. 


2. You can test the FD.TTY bit in the device characteristics 
byte (offset location F.RCTL) of the FDB to determine if the 
command line just obtained was retrieved from a terminal. 


3. In the event that error code GE.IOR or GE.OPR is returned _ to 
control block offset location G.ERR (indicating that an I/0 
error has occurred during the retrieval of a command line), 
you can test offset location F.ERR of the associated FDB for 
more complete error analysis. This cell in the FDB also 
contains an error code that may be helpful in determining the 
nature of the error condition. 


COMMAND LINE PROCESSING 


At task-build time, the Task Builder device assignment (ASG) directive 
should be issued to assign the appropriate physical device unit to the 
desired logical unit number. For example, to assign the logical unit 
number (lun parameter) in the GCMLB$ macro call (see Section 6.1.1) to 
a terminal, the following Task Builder directive should be issued: 


ASG = TI:1 


The designation TI: is a pseudo-device name that is redirected to the 
command input device. Note that the numeric value following the colon 
(:) must agree with the numeric value specified as the lun parameter 
in the GCMLBS$ macro call. 


The ASG directive is described in further detail in the Task Builder 
Reference Manual of the host operating system. 


As discussed in Section 2.6.1 on FSRSZ$, at any given time there must 
be an FSR block buffer available for each file currently open for 
record I/O operations. You must consider the buffer requirements of 
the command file when issuing the FSRSZ$ macro (FSRSZ$ must be issued 
with a nonzero first parameter). 


6.2 COMMAND STRING INTERPRETER (CSI) 


The Command String Interpreter (CSI) analyzes command lines and parses 
them into their component device name, directory, and file name 
eed Se Te ee we wet SF ke em oe Bank OT wwe ne eee ee mem a Pinan nm IK BRA 
OLL L1Nnyse ruuUu SloUusLUu Vo awaLle Lliadau wodl PLEYUVeneors ww UILUILalu Lt iLlicsS 4211 Lire 


following formats only: 
e dev:[{g,mjoutputfilespecification/switch 


More than one such file specification can be specified by 
separating them with commas. 


dev:[g,m]outputfilespecification/switch,...= dev: [g,m] 
inputfilespecification/switch,... 


> 


filename.type;version 
or 
"ANSI name string";version 


In addition, CSI maintains a dataset descriptor within the CSI control 
block (see next section) which may be used by FCS in opening files. 
The run-time routines that analyze and parse command lines for a 
calling user program are described in Section 6.2.3. 


Using CSI requires that the CSI control block offsets and bit values 
be defined and that a control block be allocated within the program. 
The macro described in the following section accomplishes’ these 
requisite actions. 
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6.2.1 CSI$ - Define CSI Control Block Offsets and Bit Values 


The only initialization coding required for CSI at assembly time is 
that shown below: 


CSI$ ;DEFINES CSI CONTROL BLOCK OFFSETS 
;AND BIT VALUES LOCALLY. 
- EVEN WORD ALIGNS CSI CONTROL BLOCK. 
CSIBLK: .BLKB C.SIZE ;NAMES CSI CONTROL BLOCK AND 
. ;ALLOCATES REQUIRED STORAGE. 


e 


The CSI$ macro is strictly definitional in nature and does not 
generate any executable code. The CSI control block resulting from 
the .BLKB directive serves as a means of communication between CSI and 
the calling program. The length of the control block is specified by 
the symbol C.SIZE, which is defined during the expansion of the CSIS$ 
macro. Expanding this macro also results in the local definition of 
the symbolic offsets and bit values within the CSI control block. 


If desired, you can cause the control block offsets to be defined 
globally within the current module. This is done by specifying DEFSG 
as an argument in the CSIS$ initialization macro call, as shown below: 


CSI$ DEFSG 


6.2.2 CSI Control Block Offset and Bit Value Definitions 


The CSI$ macro call causes the following symbolic offsets and bit 
values within the CSI control block to be defined locally: 


Offset 
Name Functional Significance 


C.TYPR Command String Request Type. This byte field. 
indicates the type of file specifier being 
requested. Depending on whether an input or 
output file specifier is being requested (see the 
io parameter in the CSIS$2 macro call, Section 
6.2.3.2), the corresponding bit in this byte is 
set. The bit definitions for this byte are as 
follows: 


CS.INP - Indicates that an input file specifier 
is being requested 


CS.OUT - Indicates that an output file 
specifier is being requested 


C.STAT Command String Request Status. This byte field 
reflects the status of the current command line 
request. The bits in this field are initialized 
in accordance with the bit definitions listed 
below: 


CS.EQU - Indicates that an equal sign (=) has 
been detected in the current command line, 
signifying that the command line contains both 
output and input file specifiers. Once set, 
the value of CS.EQU is preserved during 
Processing by both CSI1 and CSI2. 


Offset 
Name 
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Functional Significance 


CS.NMF - Indicates that the current file 
specifier contains a file name string. 
Accordingly, control block offset locations 
C.FILD+2 and C.FILD (see below) are initialized 
with the address and the length (in bytes), 
respectively, of the command line segment 
containing the file name string. If no file 
name string is present, this bit is not set, 
and the file name string descriptors in the 
control block are cleared. 


CS.DIF - Indicates that the current file 
specifier contains a directory string. fThus, 
control block offset locations C.DIRD+2 and 
C.DIRD (see below) are initialized with the 


address and the length (in bytes), 
respectively, of the command line segment 
containing the directory String. Lf no 


directory string is present, this bit is not 
set. In this case, any residual nonzero values 
in the directory string descriptor cells that 
pertain to a previous command string request of 
Similar type (see C.TYPR above) are used by 
default. Thus, the last directory string 
encountered in a file specifier is used. 


CS.DVF - Indicates that the current file 
specifier contains a device name. string. 
Similarly, control block offset locations 
C.DEVD+2 and C.DEVD (see below) are initialized 
with the address and the length (in bytes), 
respectively. of the device name strina. If no 
device name string is present, this bit is not 
set. Again, Similar to CS.DIF above, any 
residual nonzero values in the device name 
descriptor cells that pertain to a previous 
command string request of similar type are used 
by default. Thus, the last device name string 
encountered in a file specifier is used. 


CS.WLD - Indicates that the current file 
specifier contains an asterisk (*), signalling 
the presence of a wildcard specification. 


CS.MOR - Indicates that the current file 
specifier is terminated by a comma (,). The 
comma indicates that more file specifiers are 
to follow. If this bit is not set, it 
signifies that the end of the input or output 
file specifiers has been reached. 
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Offset 
Name 


C.CMLD 


C.DSDS 


C.DEVD 


C.DIRD 
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Functional Significance 


Command Line Descriptor. This 2-word field is 
initialized with the address and the length (in 
bytes), respectively, of the compressed command 
line. In other words, the values returned to 
these cells constitute the output of CSI after 
scanning a file specifier and removing all 
nonsignificant characters from the string (that 
is, nulls, blanks, tabs, and RUBOUTS). 


The values contained in these cells are used by 
CSI as the descriptors of the compressed command 
line to be parsed {see CSI$2 macro call in Section 
6.2.3.2). 


Dataset Descriptor Pointer. This offset defines 
the address of the 6-word dataset descriptor in 
the CSI control block. This structure is 
functionally identical to the manually created 
dataset descriptor detailed in Section 2.4.1. 


You can use this symbol to initialize offset 
location F.DSPT in the FDB associated with the 
file to be processed. Thus, FCS is able to 
retrieve requisite ASCII information from this 
Structure for use in opening files. 


Assembly-time initialization of F.DSPT in the 
associated FDB may be accomplished as follows: 


FDOPSA 1,CSIBLK+C.DSDS 


where CSIBLK is the address of the CSI control 
block, and C.DSDS represents the beginning address 
of the descriptor strings in the CSI control block 
(see C.DEVD, C.DIRD, and C.FILD below) identifying 
the requisite ASCII file name information. 


Run-time initialization of F.DSPT in the 
associated FDB may also be accomplished through 
the dspt parameter of the FDOPSR macro call (see 
Section 2.2.2) or the generalized OPENSx macro 
call (see Section 3.1). 


Device Name String Descriptor. This 2-word field 
contains the address (C.DEVD+2) and the length in 
bytes (C.DEVD) of the most recent device name 
string (of like request type) encountered in a 
file specifier. Note that the colon that follows 
the device name is not included in the device name 
string. 


Directory String Descriptor. This 2-word field 
contains the address (C.DIRD+2) and the length in 
bytes (C.DIRD) of the most recent directory string 
(of like request type) encountered in a file 
specifier. 


Offset 
Name 


C.FILD 


C.SWAD 


C.MKW1 


C.MKW2 


C.SIZE 
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Functional Significance 


File Name String Descriptor. This 2-word field 
contains the address (C.FILD+2) and the length in 
bytes (C.FILD) of the file name string in the 
current file specifier. 


If an error condition is detected by the command 
syntax analyzer during the syntactical analysis of 
a command line (see Section 6.2.3.1 below), a 
segment descriptor is returned to this field, 
defining the address and the length of the command 
line segment in error. 


Current Switch Table Address. This word location 
contains the address of the switch descriptor 
table specified in the current CSI$2 macro call 
(see Section 6.2.3.2). 


CSI Mask Word 1. This word indicates the 
particular switch(es) present in the current file 
specifier after each invocation of the CSI$2 macro 
Gall. The switch mask for each of the defined 
switches encountered in a file specifier between 
delimiting commas is inserted into this location 
by a logical OR operation into this location. 


The mask for a Switch is specified in the CSISSW 
macro call (see Section 6.2.4.1). When a switch 
is encountered in a file specifier for which a 
defined mask exists, the corresponding bits in 
C.MKW1l are set. By testing C.MKW1l, you can 
determine the particular combination of defined 
switches present in the current file specifier. 


CSI Mask Word 2. This word provides you with an 
indication of switch polarity. 

When a Switch is present in a file specifer and 
that switch is not negated, the defined mask for 
that switch is inserted into C.MKW2 by a logical 
OR operation in the same manner as described above 
for C.MKW1l. Conversely, when a switch is. present 
in a file specifer and that switch is negated, the 
corresponding bits in C.MKW2 are cleared. Thus, 
for each switch indicated as being present by 
C.MKW1, you can check the polarity of that switch 
by examining the corresponding bits in C.MKW2. 
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Control Block Size Indicator. This symbol, which 
is defined during the expansion of the CSIS$ macro, 
represents the size in bytes of the CSI control 
block. 
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6.2.3 CSI Run-Time Macro Calls 


Two run-time macro calls are provided in CSI to invoke routines’ that 
perform the following functions: 


CSI$1 - Initializes the CSI control block, analyzes the command 
line (normally contained in the GCML command line input 
buffer), removes nonsignificant characters from the 
line, and checks it for syntactic validity. This macro 
call also results in the initialization of certain cells 
in the CSI control block with the address and the 
length, respectively, of the validated and compressed 
command line. 


CSISZ2 - Parses a file specifier in the validated and compressed 
command line into its component device name, directory, 
and file name strings, and processes any associated 
switches and accompanying switch values. Also, certain 
cells in the CSI control block are initialized with the 
appropriate string descriptors for subsequent use by FCS 
in opening the specified file. 


6.2.3.1 CSI$1 - Command Syntax Analyzer - The CSTs macro call 
results in the invocation of a_ routine called the command syntax 
analyzer. This routine analyzes a command line (which is normally 
read into the GCML command line input buffer) and checks it for 
syntactic validity. In addition, it compresses the file specifiers in 
the command line by removing all nonsignificant characters (that is, 
nulls, RUBOUTs, and unquoted tabs and blanks). Finally, the command 
Syntax analyzer initializes offset locations C.CMLD+2 and C.CMLD in 
the CSI control block (see Section 6.2.2) with the address and _ the 
length (in bytes), respectively, of the validated and compressed 
command line. Each file specifier in the command line is then parsed 
into its component device name, directory, and file name strings 
during successive issuances of the CSI$2 macro call (see next 
section). 


The CSI$1 macro call is issued in the following format: 


CSIiS) csiblk,buff,len 


csiblk 


The address of the CSI control block. If this parameter is not 
specified, RO is assumed to contain the address of the CSI 
control block. 


buff 


The address of a command line input buffer. This parameter 
initializes CSI control block offset location C.CMLD+2, enabling 
CSI to retrieve the current command line from a command line 
input buffer. 


If this parameter is not specified, you must manually initialize 
CSI control block offset location C.CMLD+2 with the address of a 
command line input buffer before issuing the CSI$l1 macro call. 
This may be accomplished through a _ statement similar to the 
following: 


MOV GCLBLK+G.CMLD+2,CSIBLK+C.CMLD+2 
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len 


The length of the command line input buffer. Similarly, this 
parameter initializes CSI control block offset location C.CMLD, 
thus completing the 2-word descriptor that enables CSI to 
retrieve the current command line from the input buffer. 


As with the buff parameter above, if this parameter is not 
specified, you must manually initialize CSI control block offset 
location C.CMLD with the length of the command line input buffer 
before issuing the CSI$1 macro call. This may be accomplished as 
follows: 


MOV GCLBLK+G.CMLD,CSIBLK+C.CMLD 


The combination of the buff and len parameters above enables CSI _ to 
analyze the current command line. Following the analysis of the 
command line, CSI updates offset location C.CMLD with the length of 
the validated and compressed command line. 


If a syntactical error is detected during the validation of the 
command line, the C-bit in the Processor Status Word is set, and 
offset locations C.FILD+2 and C.FILD in the CSI control block (see 
Section 6.2.2) are set to values that define the address and the 
length, respectively, of the command line segment in error. 


Examples of the CSIS$1 macro call follow: 


CSIS$1 #CSIBLK, #BUFF, #LEN 

CSISL RO, GCLBLK+G.CMLD+2 ,GCLBLK+G.CMLD 

CSIS$1 #CSIBLK 
The first example shows symbols that represent tne address and the 
length of a command line to be analyzed (not necessarily the line 


contained in the GCML command line input buffer). 


The second example assumes that RO has been preset with the address of 
the CSI control block; the next two parameters are direct references 
to the command line descriptor words in the GCML control biock. 


The third example assumes that the required descriptor values are 
already present in offset locations C.CMLD+2 and C.CMLD of the control 
block (CSIBLK) as the result of prior action. 


6.2.3.2 CSI$2 - Command Semantic Parser - The CSIS$2 macro call 
results in the invocation of the command semantic parser. This 
routine uses the values in CSI control block offset locations C.CMLD+2 
and C.CMLD as the address and the length, respectively, of the command 
line to be parsed. The referenced line is then parsed into its 
component device name, directory, and file name strings. The equal 
sign (=) in the command line indicates that the following string is an 
input file specification. In addition, 2-word descriptors for these 
Strings are stored in a 6-word dataset descriptor in the CSI control 
block, beginning at offset location C.DSDS (see Section 6.2.2). This 
field is functionally equivalent to the dataset descriptor created 
manually in your program (see Section 2.4.1). 
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The command semantic parser also decodes any switches and associated 
Switch values present in a file specifier. If you expect to encounter 
switches in the current file specifier, the command semantic parser 
decodes them, provided that the address of the appropriate switch 
descriptor table has been specified in the CSI$2 macro call (see 
below). The CSI switch definition macro calls are described in detail 
in Section 6.2.4. 


The CSI$2 macro call is specified in the following format: 


CSI$2 csiblk,io,swtab 


csiblk 


The address of the CSI control block. If this parameter is nob 
specified, RO is assumed to contain the address of the CSI 
control block. 


io 


A symbol that explicitly identifies the type of file specifier to 
be parsed. Either of two symbolic arguments may be specified in 
this parameter field, as follows: 


INPUT - Indicates that the next input file specifier in the 
command line is to be parsed 


OUTPUT - Indicates that the next output file specifier in the 
command line is to be parsed 


Offset location C.TYPR in the CSI control block (see Section 
6.2.2) must be initialized, either manually or through the CSI$2 
macro call, with the type of file specifier being requested. Tf 
arguments other than the symbolic arguments defined above are 
specified in the CSI$2 macro call, an .ERROR directive is 
generated during assembly that causes the error message INCORRECT 
REQUEST TO .CSI2 to be printed in the assembly listing. This 
diagnostic message alerts you to the presence of an invalid io 
parameter in the CSI$2 macro call. 


swtab 


The address of the associated switch descriptor table for this 
particular issuance of the CSI$2 macro call. This optional 
parameter need be specified only when you anticipate the presence 
of a switch in the file specifier that is to be decoded. 
Specifying this parameter presumes that you previously created a 
corresponding switch descriptor table in the program through the 
CSISSW macro call (see Section 6.2.4.1). In addition, if the 
switch to be decoded has any associated switch values, you must 
also have created an associated switch value descriptor table in 
the program through the CSISSV macro call (see Section 6.2.4.2). 


This parameter initializes offset location C.SWAD in the CSI 
control block (see Section 6.2.2); if not specified, any 
residual nonzero value in this cell is used by default as_ the 
address of the switch descriptor table. 
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You can also initialize offset location C.SWAD manually prior to 
issuing the CSI$2 macro call, as shown in the following 
statement: 


MOV #SWTAB,CSIBLK+C.SWAD 


where SWTAB is the symbolic address of the associated switch 
descriptor table. 


The switch table must be aligned on an even address. 


If an error condition occurs during the parsing of the file specifier, 
the C-bit in the Processor Status Word is set, and control is returned 
to the calling program. The possible error conditions that may occur 
during command line parsing include the following: 


e The request type was invalid; that is, offset location C.TYPR 
in the CSI control block (see Section 6.2.2) was incorrectly 
initialized. 


e A switch was present in a file specifier, but the address of 
the switch descriptor table was not specified in the CSIS2 
macro call, or the switch descriptor table did not contain a 
corresponding entry for the switch. 


e An invalid switch value was present in the file specifier. 


e More values accompanied a given switch in the file specifier 
than there were corresponding entries in the switch value 
descriptor table for decoding those values. 


e A negative switch was present in the file specifier, but the 
corresponding entry in the switch descriptor table did not 
allow the switch to be negated (see the nflag parameter of the 
CSISSW macro call in the next section). 


Examples of the CSI$2 macro call are shown below: 
CSIS$2 #CSIBLK, INPUT, #SWTBL 
CSIS$2 RO,OUTPUT, #SWTBL 
CSI$2 #CSIBLK, INPUT 


The first example shows a request to parse an input file specifier, 
which may include an associated switch. The second example, which 
assumes that RO presently contains the address of the CSI control 
block, parses an output file specifier that also may include a switch. 
The last example is a request to parse an input file specifier and to 
disallow any accompanying switches. 


6.2.4 CSI Switch Definition Macro Calls 


You must issue the following macro calls at assembly time to create 
the requisite switch descriptor tables in the program for processing 
switches that appear in a file specifier: 


CSISSW - Creates an entry in the switch descriptor table for a 
particular switch that you expect to encounter ina file 
specifier 


CSISSV - Creates a matching entry in the switch value descriptor 
table for the switch defined through the CSISSW macro 
call above 
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CSISND - Terminates a switch descriptor table or a switch value 
descriptor table created through the CSISSW or the 
CSISSV macro call, respectively 


These macro calls are described separately in the following sections. 


6.2.4.1 CSISSW - Create Switch Descriptor Table Entry - To process 
each switch that you expect to encounter ina file specifier, a 
matching entry in the switch descriptor table must be defined. If no 
Switch descriptor table is specified, the presence of any switch in 
the command line causes an error to occur. When the address of a 
switch descriptor table is specified in any particular issuance of the 
CSI$2 macro call (see Section 6.2.3.2), the following processing 
occurs: 


l. For each switch encountered in a file specifier, CSI searches 
the switch descriptor table for a matching entry. If the 
Switch descriptor table address is not specified, or a 
matching entry is not found in the table for the switch, that 
switch is considered to be invalid. As a result, the C-bit 
in the Processor Status Word is set, any remaining switches 
in the file specifier are bypassed, and control is’ returned 
to the calling program. 


2. If a matching entry is found in the switch descriptor table, 
mask word 1 in the CSI control block is set according to the 
defined mask for that switch (see C.MKW1, Section 6.2.2). 


3. The negation status of the switch is determined. If the 
switch is not negated, the corresponding bits in mask word 2 
(C.MKW2) in the CSI control block are set according to the 
defined mask for that switch. If the switch is negated, and 
negation is not allowed, then the switch is considered to be 
invalid. In this case, the error Sequence described in step 
l above applies. However, if the switch is negated, and 
negation is allowed, then the corresponding bits in C.MKW2 
are cleared. 


The negation flag for a switch is established through the 
nflag parameter of the CSISSW macro call (see below). 


4, If the address of the optional user mask word is not’ present 
in the corresponding switch descriptor table entry, that is, 
if the mkw parameter has not been specified in the associated 
CSISSW macro call (see below), switch processing continues 
with step 7. If, however, the address of the optional mask 
word is specified, switch processing continues with step 5. 


5. If SET has been specified as the clear/set flag in the 
corresponding switch descriptor table entry, and the switch 
is not negated, then the corresponding bits in the optional 
mask word are set according to the defined mask for that 
switch. ity however, the switch is negated, the 
corresponding bits in the optional mask word are cleared. 


The clear/set flag is specified as the csflg parameter in the 
CSISSW macro call (see below). 


6. If CLEAR has been specified as the clear/set flag in the 
corresponding switch descriptor table entry, and the switch 
is not negated, the corresponding bits in the optional mask 
word are cleared. Conversely, if the switch is negated, the 
corresponding bits in the optional mask word are set. 
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7. .IIf a switch value accompanies a switch in a file specifier, 
the associated switch value descriptor table created through 
the CSISSV macro call (see next section) is used to decode 
the value. There must be at least as many entries in the 
Switch value descriptor table as there are such values 
accompanying the switch in the file specifier. If the switch 
value descriptor table is incomplete, if an invalid switch 
value iS encountered, or if the address of the switch value 
descriptor table is not present in the associated switch 
descriptor table, then the switch is considered to be 
invalid, and the error sequence described in step 1 again 
applies. 


The address of the switch value descriptor table is specified 
as the vtab parameter in the CSISSW macro call (see below). 


The CSISSW macro call is specified in the following format: 


label 


SW 


mk 


label: CSISSW sw,mk,mkw,csflg,nflg,vtab,compflg 


An optional symbol that names the resulting switch descriptor 
table entry and defines its address. In order to establish the 
address of a switch descriptor table, the first CSISSW macro call 
issued in the program must include a label. This label allows 
the table to be referenced by other instructions in the program. 


The alphabetic switch name to be stored in the switch descriptor 
table. This name may comprise any number of characters. CSI 
compares the name entered on the command line with this switch 
name, as entered in the switch descriptor table. The method CSI 
uses to compare their names is described below. This parameter 
is required. If omitted, an .ERROR directive is generated during 
assembly that causes the error message MISSING SWITCH NAME to be 


printed in the assembiy listing. 


A user-defined mask for the switch specified through the sw 
parameter above. To enable CSI to indicate the presence of a 
given switch in a file specifier, a mask value for the switch 
must be defined, as shown below: 


ASMSK = 1 
NUMSK = 2 
VWMSK = 40000 
XYMSK = 100000 


where the (octal) value that you assign to each symbol defines a 
unique bit configuration that is to be set in CSI mask word 1 
(C.MKW1) of the control block when a defined switch is 
encountered in a file specifier. 


mkw 


csflg 


nflg 
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When you specify the appropriate symbol as the mk parameter in 
the CSISSW macro call, the corresponding mask value is stored in 
the resulting switch descriptor table entry. Thus, a mechanism 
is established through which you can determine the particular 
combination of switches present in a file specifier. For every 
matching entry found in the switch descriptor table, the 
corresponding bits are set in C.MKW1. 


The address in your program storage of a mask word that CSI 
changes each time it changes C.MKW1l. CSI stores the same value 
into this mask word that it stores into C.MKWl. This mask word 
can be manipulated (that is, changed or tested) by the SET and 
CLEAR functions or by instructions in your program. You set’ the 
SET and CLEAR functions using the csflg parameter described 
below. 


Such an optional word may be reserved through a_ statement 
logically equivalent to that shown below: 


MASKX: .WORD 0 


A symbolic argument that specifies the clear/set flag for a given 
switch. This parameter is optional; if not specified, SET is 
assumed (see below). Either one of two symbolic arguments may be 
specified for this parameter, as follows: 
CLEAR - Indicates that the bits in the optional user mask word 
corresponding to the switch mask are to be cleared, provided 
that the switch is not negated. (If the switch is negated, 
the bits are set.) 


SET - Indicates, conversely, that the bits in the optional 
user mask word corresponding to the switch mask are to be set 
provided that the switch is not negated. (If the switch is 
negated, the bits are cleared.) 


If other than one of the above arguments is specified, an .ERROR 
directive is generated during assembly that causes the error 
message INVALID SET/CLEAR SPEC to be printed in the assembly 
listing. 


A symbolic argument that specifies an optional negation flag for 
the switch. If this parameter is specified, it indicates that 
the switch is allowed to be negated, for example, /-LI or /NOLI. 


If this parameter is specified as other than NEG, an_ .ERROR 
directive is generated during assembly that causes the error 
message INVALID NEGATE SPEC to be printed in the assembly 
listing. If this parameter is not specified, the default 
assumption is that switch negation is not allowed. 
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vtab 


The address of the switch descriptor table associated with this 
switch. This optional parameter, if specified, allows CSI to 
decode any switch values accompanying the switch, provided that 
an associated switch descriptor table entry has been defined for 
that switch. The switch value descriptor table is defined 
through the CSISSV macro call, as described in the next section. 
(If the vtab parameter is specified in the CSISSV macro call, 
there is no need to specify it in the CSISSW macro call.) 


compflg 


The method CSI uses to compare the switch name entered on _ the 
command line with the value entered in the switch descriptor 
table by the sw parameter. Either LONG or EXACT may be 
specified. The default value is entered if a value is not coded. 


Default - If the parameter is not coded, only the first two 

characters of the switch name (specified by sw) are entered into 

the switch descriptor table and only these two characters are 
ated 
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LONG - All characters specified by the sw parameter are _ entered 
in the switch descriptor table. During compare processing, the 
first characters of the switch name on the command line must 
exactly match the value for the switch in the switch descriptor 
table. Additional characters in the command line switch name are 
ignored. 


EXACT - All characters specified by the sw parameter are entered 
in the switch descriptor table. During compare processing, all 
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exactly match the value in the switch descriptor table. Extra 
characters are treated as an error. 


The switch table must be aligned on an even address. 


The format of the switch descriptor table entry that results from a 
call to the CSISSW macro is shown in Figure 6-2 below. One such 
switch entry must be defined for each switch appearing in the file 
specifier that you intend to recognize. Entries in the switch 
descriptor table consist of control information and switch name 
characters stored two characters per word. 


The switch name characters precede the control information in the 
table. The sign bit of each word indicates whether the following word 
contains more switch name characters. A Sign bit set to 1 indicates 
that the next word contains more switch name characters, whereas sign 
bit set to 0 indicates the last word containing switch name 
characters. 


If the number of characters in the switch name is odd, the high-order 
byte of the last word contains zeros and is ignored by CSI. 


The sign bit of the first byte of the last word of the switch name is 
the EXACT match bit. If this bit is set to 1, additional characters 
in the switch name on the command line are treated as an error by CSI. 
Otherwise, they are ignored. 


6-26 
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The switch name characters are followed by entry control information 
consisting of the CSI mask word, the address in user program storage 
of a mask word corresponding to the CSI mask word, and the address of 
the switch value table. 


A bit setting of 1 in the low-order bit of the address of your mask 
word indicates the CLEAR function; a bit setting of 0 indicates the 
SET function. 

The last word of the switch descriptor table entry contains’ the 


address of the switch value table. A bit setting of 1 in the 
low-order bit of this word indicates that the switch may be negated. 


15 0 
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Mask Word for this Switch 


Address of Optional User Mask Word 


Address of Switch Descriptor Table 
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Figure 6-2 Format of Switch Descriptor Table Entry 


The following example shows a 2-entry switch descriptor table created 
through successive CSISSW macro calls: 


ASSWT: CSISSW AS,ASMSK,MASKX,SET,,ASVTBL 
CSISSW NU,NUMSK,MASKX,CLEAR,NEG,NUVTBL 
CSISND 7;END OF SWITCH DESCRIPTOR TABLE. 


The first statement results in the creation of an entry in the switch 
descriptor table for the switch /AS. The second parameter is an 
equated symbol that defines the switch mask, and the third parameter 
(MASKX) is the address of an optional user mask word (see the mkw 
parameter above). The fourth parameter indicates that the bits in 
MASKX that correspond to the switch mask are to be set. The fifth 
parameter (the negation flag) is null. The last parameter is the 
address of the associated switch value descriptor table. 


The second statement results in the creation of a switch descriptor 
table entry for the switch /NU. In contrast to the first statement, 
the fourth parameter (CLEAR) indicates that the bits in the optional 
user mask word (MASKX) that correspond to the switch mask are to be 
cleared. The fifth parameter (NEG) allows the switch to be negated, 
and the last parameter is the address of the value table associated 
with this switch. 


Note that the switch descriptor macros are terminated with the CSISND 
macro call (see Section 6.2.4.3). 
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6.2.4.2 CSISSV - Create Switch Value Descriptor Table Entry - For ev- 
ery switch value that you expect to encounter in connection with a 
given switch in a file specifier, a corresponding switch value 
descriptor table entry must be defined in your program in order to 
allow the switch value(s) to be decoded. The CSISSV macro call is 
provided for this purpose. When issued, this macro call results in 
the creation of a 2-word entry in the switch value descriptor table. 
The format of this table is shown in Figure 6-3 below. 


The CSISSV macro call is specified in the following format: 


CSISSV type,adr,len 


type 


A symbolic argument that specifies the conversion type for the 
Switch value. Any one of four symbolic values may be specified 
in this parameter field to indicate the conversion type for the 
accompanying Switch value. The possible conversion-type 
arguments include the following: 


ASCII - Indicates that the switch value is to be treated as an 
ASCII string. If the string is quoted, the quotes are 
returned in the buffer as part of the _ string. If a quote 
appears anywhere in the switch value, all characters following 
it, up to end-of-line or another quote are included in the 
String. 


NUMERIC - Indicates that a numeric switch value is to be 
converted to binary using octal as a default conversion radix. 


OCTAL - Indicates that a numeric switch value is to be 
converted to binary using octal as a default conversion radix. 


ates that a numeric switch value is to be 
converted to binary using decimal as a default conversion 


radix. 


If any value other than those defined above is specified, an 
-ERROR directive is generated during assembly that causes the 
error message INVALID CONVERSION TYPE to be printed in the 
assembly listing. If none of the above parameters is specified, 
ASCII is assumed by default. 


adr 


The address of your program location that is to receive the 
resultant switch value at the conclusion of switch processing. 
This parameter is required; if not specified, an . ERROR 
directive is generated during assembly that causes the error 
message VALUE ADDRESS MISSING to be printed in the assembly 
listing. 


len 


A numeric value that defines the length (in bytes) of the area 
that is to receive the switch value resulting from switch 
processing. This parameter is also required; if not specified, 
an .ERROR directive is generated during assembly that causes the 
error message LENGTH MISSING to be printed in the assembly 
listing. 
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The format of a switch value descriptor table entry that results from 
the CSISSV macro call is shown in Figure 6-3 below. 


The low-order byte of the first word in the switch value descriptor 
table indicates whether the conversion type is ASCII or numeric. The 
low-order byte of this word is set to 1 if ASCII is specified; it is 
set to 2 if NUMERIC or OCTAL is specified, and is set to 3 if DECIMAL 
is specified. The high-order byte of this word indicates the maximum 
allowable length (in bytes) of the switch value. 


If the conversion type is ASCII, the len parameter reflects’ the 
maximum number of ASCII characters that can be deposited in the area 
defined through the adr parameter. The high-order byte of the first 
word in the switch value table then reflects the maximum length of the 
ASCII string. If the number of characters in the switch value exceeds 
the specified length, the extra characters are simply ignored. If, 
however, the actual number of ASCII characters present in the switch 
value falls short of the specified length, the remaining portion of 
the area receiving the resultant value is null padded. 


If the conversion type is numeric, the length of the resulting binary 
value is either two bytes or four bytes. If the size field is less 
than 4, 2 bytes are stored. If the size field is greater than 4, 4 
bytes are stored. The buffer must be aligned on a word-boundary. 


On numeric conversions, the default conversion type specified for a 
switch value can be overridden by means of a pound sign (#) or a dot 
(.). A numeric value preceded by a pound sign (for example, #10) 
forces the conversion type to octal; a numeric value followed by a 
dot (for example, 10.) forces the conversion type to decimal. Note 
also that a numeric switch value may be preceded by a plus sign (+) or 
a minus sign (-). The plus sign is the default assumption. If an 
explicit octal switch value is specified using the pound sign (#), as 
described above, the arithmetic sign indicator (+ or -), if included, 
must precede the pound sign (for example, -#10). 


If the conversion type is decimal, the switch value is evaluated as a 
Single number; an overflow into the high-order bit (bit 15) results 
in an error condition. However, if the conversion type is octal, a 
full 16-bit value may be specified. 


16 0 


Switch Value Length Conversion Type 


Address of Location Receiving Switch Result 
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Figure 6-3 Format of Switch Value Descriptor Table Entry 
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Representative CSISSV macro calls are shown below: 
ASVTBL: CSIS$SV ASCII,ASVAL,3 
CSISSV ASCII,ASVAL+4,3 
CSISND ;END OF SWITCH VALUE TABLE. 
NUVTBL: CSISSV OCTAL,NUVAL, 2 
CSISSV DECIMAL,NUVAL+2,2 
CSISND ;END OF SWITCH VALUE TABLE. 
In all cases above, the first parameter in the CSISSV macro call 
defines the conversion type. The next two parameters, in all cases, 
define the address and the length of your program location that is to 


receive the resultant switch value. 


The required storage for the first switch value table above may be 
reserved as follows: 


ASVAL - BLKW 4 ;ASCII VALUE STORAGE. 


The required storage for the second switch value table may be 
Similarly reserved through the following statement: 


NUVAL: .BLKW 2 ;NUMERIC VALUE STORAGE. 


Note again that switch value tables are terminated with the CSISND 
macro call. 


6.2.4.3 CSISND - Define End of Descriptor Table - Switch descriptor 
tables and switch value descriptor tables must be terminated with a 
l-word end-of-table entry. This word, which contains 0, may be 
created through the CSISND macro call. 


This macro call takes no arguments, as shown Dbeiow: 
CSISND 


The examples near the end of the preceding section illustrate the use 
of this macro call. 


CHAPTER 7 


THE TABLE-DRIVEN PARSER (TPARS) 


TPARS is a table-driven parser designed to parse command lines. MTPARS 
provides the means to define a unique syntax and, using TPARS-supplied 
macros, built-in variables, and your own code, recognize a command 
line written in that syntax. 


For TPARS, parsing is breaking down a command line into syntax 
elements and resolving the form, function, and interrelationship of 
these elements. TPARS parses command lines at two levels: 
syntactical and semantic. At the syntactical level, TPARS evaluates 
each syntax element on the command line based on a_e predefined 
arrangement of command line elements. This arrangement of command 
line elements is defined by TPARS macros in a state table that 
consists of states and transitions. Also at the syntactical level, 
TPARS provides for resolving complex syntax types by means of 
subexpressions. On the semantic level, TPARS resolves the meaning of 
each element based on definitions supplied in action routines. Action 
routines make use of TPARS built-in variables and uSer-Supplied code 
to fit the needs of a user parsing routine. 


TPARS parses command lines using a user-defined table. You can build 
a state table using the TPARS STATES and TRANS macros. A state 
delimits and represents a single syntax element on a command line. A 
transition is a statement that defines the processing required for 
parsing a given syntax element and provides direction for further 
parsing at another state. 


The user-written parser routine is included in user programs’ that 
parse command lines. TPARS is invoked from within an executing 
Program by means of a CALL instruction. The CALL invokes’ the 
user-defined parser routine as well as the TPARS processor itself. 
For further information on the interrelationships between the calling 
program, the user-defined parser routine, and the TPARS processor, 
refer to Section 7.5. 


7.1 CODING TPARS SOURCE PROGRAMS 


This section describes the three TPARS macros required to initialize 
and define the state table. Also included in this section is 
information describing action routines, TPARS built-in variables, and 
TPARS subexpressions. 
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7.1.1 TPARS Macros: ISTATS, STATES, and TRANS 


TPARS provides macros that allow you to write a state table for 
parsing a unique command line syntax. The ISTATS macro initializes a 
state table, the STATES macro defines a state in your state table, and 
the TRANS macro defines the conditions for transition to another 
state. 


7.1.1.1 Initializing the State Table: the ISTAT$ Macro - The ISTATS 
macro initializes the state table. The state table is built using two 
macros, STATES and TRANS, which are described below. This state table 
is built into a program section. User-defined keyword strings, for 
use in parsing command lines, are also accumulated in a _= program 
section. A program section is also provided for a keyword pointer 
table to index into the list of keyword strings. The ISTATS macro 
initializes these program sections. The format for coding the ISTATS 
macro is: 


ISTATS statetable,keytable,$DEBUG 
statetable 


The label that you assign to the state table. TPARS equates this 
label to the start of the state table. 


keytable 


The label that you assign to the keyword table. TPARS equates 
this label to the start of the keyword table. 


SDEBUG 


Directs the assembler to list addresses of the state transition 
table in the assembly listing. These addresses are useful for 
tracing TPARS operation using a user-supplied debug routine (see 
Section 7.1.3.4). When SDEBUG is not included, state transition 
table addresses are not listed. 


The state table is built in a program section named SSTATE; the 
keyword strings are accumulated in a program section named SKSTR; the 
keyword pointer table is built in a program section named S$KTAB. 


If you define the symbol SRONLY, each of these program sections is 
generated as_ read-only. You generate a read-only state table by 
specifying the symbol SRONLY preceding the ISTATS macro in the form: 


SRONLY = 1 
ISTATS statetable,keytable,SDEBUG 


THE TABLE-DRIVEN PARSER (TPARS) 


7.1.1.2 Defining a Syntax Element: the STATES Macro - The STATES 
macro declares the beginning of a state. Syntactically, this macro 
delimits one command line element from another. The STATES macro is 
coded in the following form: 

STATES [label] 
label 


An alphanumeric symbol that is equated to the address of the 
state. 


Each state is comprised of any number of transitions, which define the 
conditions under which control can be passed to another state. 


7.1.1.3 Defining a Transition: the $TRAN Macro - The TRANS macro 
provides: 


@ The means for matching a given type of syntax element 
e Direction to the next state to be processed 


e The address of the action routine to process the current 
syntax element 


e A maskword and maskword address 
The TRANS macro is coded in the following form: 


TRANS type[,label][,action] [,mask] [,maskaddr] 


[,$EXIT] 

type 
The syntactical type of the command line element being parsed. 
The type parameter is coded using one of the types of command 
line elements described in the Section, "Types of Command Line 
Syntax Elements," below. 

[label] 

{SEXIT] 
The label associated with the state to which control is directed 
after the code for this transition is executed. If label is 
omitted, control drops through to the next sequential STATES 
macro. A null label parameter is allowed only for the last 
transition in a state; the statement following a TRANS macro 
with a null label field must be a STATES macro. 
SEXIT specified in the label field terminates TPARS execution and 
returns control to the calling program. SEXIT is also used to 
terminate a TPARS subexpression. 

action 


The label of an action routine the user includes in the parser 
routine. This routine can include TPARS built-in variables, 
described in Section 7.1.3 below. 


mask 
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A maskword to be stored into a maskword address whenever’ the 
transition is executed. If mask is specified, maskaddr, below, 
must be specified. This maskword is  ORed into maskaddr 
(described below) when the transition is taken (after the action 
routine is called). 


maskaddr 


7.1.2 


The label for an address into which TPARS stores the value 
specified by the mask parameter. The maskaddr parameter must be 
specified if mask is specified. 


The mask and maskaddr parameters provide a convenient means’ for 
flagging the execution of a particular transition. 


Types of Command Line Syntax Elements 


The type parameter of the TRANS macro requires the entry of one of the 
following types of syntax elements: 


SANY Matches any single character. 

SALPHA Matches any Single alphabetic character (A-Z). 

SDIGIT Matches any Single digit (0-9). 

SLAMDA Matches an empty string. This transition is 
always successful. LAMDA transitions are useful 


for getting action routines called without passing 
any of the input string. 


SNUMBR Matches a number. A number consists of a _ string 
of digits, followed optionally by a period. If 
the number is not followed by a period, it is 
interpreted as octal. Numbers followed by a 
period are interpreted as decimal and the decimal 
point is included in the matching string. A 
number is terminated by any nonnumeric character. 
Values through 2**32-1 are converted to 32-bit 
unsigned integers. 


SDNUMB Matches a decimal number. The string of digits is 
interpreted as decimal. With the exception that 
the matched string does not include the trailing 
decimal point, TPARS treats S$DNUMB the same way it 
treats SNUMBR. 


SSTRNG Matches any alphanumeric character string 
(0-9,A-Z). The string will not be null. 


SRAD50 Matches any legal RADIX-50 string, that is, any 
String containing alphanumeric characters and/or 
the period (.) and dollar sign ($) characters. 
Conversion to RADI X-50 format is the 
responsibility of the action routine. 
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SBLANK Matches a string of blank and/or tab characters. 


SEOS Matches the end of the input string. Once TPARS 
has reached the end of the input string, S$EOS 
matches as many times as it is encountered in the 
state table. 


char Matches a Single character whose ASCII code 
corresponds to the value of the expression char. 
The value of the expression must be a 7-bit ASCII 
code; that is, the value must be in the range 
0-177 (octal). Constructions such as 'X are valid 
and, in fact, recommended. 


"keyword" Matches a specified keyword. Keywords may be any 
length, may contain only alphanumeric characters, 
and are terminated by the first nonalphanumeric 
character encountered. The maximum number of 
keywords allowed in a state table is 64. 


!label Matches the string processed by executing the 
State table section that starts with the state 
specified as label. This syntax type is uSed to 
pass control to a subexpression. For information 
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7.1.3 Action Routines and Built-in Variables 


Action routines provide the means for processing command line elements 
at the semantic level. That is, a given syntax element can have more 
than one meaning. Action routines provide a mechanism for determining 
and validating the meaning of the syntax elements. 


Write action routines to perform functions related to the unique 
requirements of your parsing program. 


7.1.3.1 TPARS Built-in Variables - TPARS provides the following 
built-in variables for use in action routines: 


- PSTCN Returns the character count of the portion of the 
input string matched by this transition. This 
character count is valid for all syntax types 
recognized by TPARS, including subexpressions. 


»PSTPT Returns the address of the portion of the input 
String matched by this transition. This address 
is valid for all syntactical types recognized by 
TPARS, including subexpressions. 


. PNUMH Returns the high-order binary value of the number 
returned by a SNUMBR or SDNUMB syntax type 
specification. 


- PNUMB Returns the low-order binary value of the number 
returned by a SNUMBR or S$DNUMB syntax type 
specification. 


THE TABLE-DRIVEN PARSER (TPARS) 


- PCHAR Returns the character found by the SANY, SALPHA, 
SDIGIT, or char syntax type specifications. 


. PFLAG Returns the value of the flag word passed to TPARS 
by register 1 (Rl). Action routines can modify 
this word to change options dynamically. 


» TPDEB Contains the entry address of the optional 
(user-supplied) debug routine. 


R3 Returns the byte count of the remainder of the 
input string. When the action routine is called, 
the string does not include the characters matched 
by the current transition. 


R4 Returns the address of the remainder of the input 
string. When the action routine is called, the 
String does not include the characters matched by 
the current transition. 


7.1.3.2 Calling Action Routines - Action routines are called by a JSR 
PC instruction. Action routines may modify registers RO, Rl, and R2; 
all other registers must be preserved. 


7.1.3.3 Using Action Routines to Reject a Transition - Action rou- 
tines can reject a transition by returning to CALL+4 rather than to 
CALL+2. That is, the action routine performs the same function aS an 
ADD #2,(SP) before returning to the caller. This technique allows 
additional processing of syntax types and extending the syntax types 
beyond the set provided by TPARS. 


When an action routine rejects a transition, that transition has no 
effect. TPARS continues to attempt to match the remaining transitions 
in the state. 


7.1.3.4 Optional Debug Routine for RSX-11l Users - A user-supplied 
debug routine can be called by TPARS at each state transition allowing 
TPARS operation to be traced. For example, the routine can be written 
to display the contents of R5 each time the routine is called; R5 
contains the current transition table address. By comparing the 
addresses displayed with the TPARS assembly listing showing the state 
transition table addresses, TPARS operation can be monitored. 


If a user-supplied debug routine is to be called by TPARS, the user 
task must first specify the entry point address for the debug routine 
in TPARS location .TPDEB, as follows: 

MOV #DENTER, .TPDEB 


Then, invoke TPARS with the .TPARD entry point (rather than with 
-TPARS). TPARS is invoked as described in Section 7.4. 
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Upon entry to the debug program, CPU registers contain the following: 


R3 = Length of remainder of input string 


R4 Address of remainder of input string 


R5 = Current address of transition table 


The debug routine must save and restore all registers prior to 
returning to TPARS. 


In order for addresses displayed by the debug routine to be useful, it 
is necessary to obtain an assembly listing showing the addresses of 
the state transition tables. These addresses are listed by the 
assembler if the optional $DEBUG parameter is provided in the ISTATS 
macro call (see Section 7.1.1.1). 


7.1.4 TPARS Subexpressions 


A TPARS subexpression is a series of states and transitions analogous 
to a subroutine. In general, such a series of states and transitions 
is used more than once during the parsing process. 


Subexpressions begin with a STATES macro specifying the label of the 
subexpression. This macro is followed by the states and transitions 
that comprise the body of the subexpression. To terminate the 
subexpression, specify a TRANS macro with the SEXIT keyword specified 
in the label field. The general form of a subexpression is shown in 
the example below. 


In this example, control is directed to the subexpression by a TRANS 
macro that specifies a !label syntax element as the type parameter: 


TRANS !UIC,;NEXT 
TPARS then directs control to the STATES macro with the label UIC: 


STATES UIC 
TRANS '[ 


STATES 
TRANS SNUMBR,,SETGN 


STATES 
TRANS ',> 


STATES 
TRANS SNUMBR,,SETPN 


STATES 
TRANS '],SEXIT 


When the UIC subexpression completes processing, control passes to the 
State labeled NEXT. 
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7.2 GENERAL CODING CONSIDERATIONS 


This section contains information on how to arrange syntax types in a 
State table and how to direct TPARS to ignore blanks and table 
characters in a command line, and rules for entering special 
characters (commas and angle brackets). 


7.2.1 Suggested Arrangement of Syntax Types in a State Table 


The transitions in a state may represent several syntax types; a 
portion of a string being scanned often matches more than one syntax 
type. Therefore, the order in which the types are entered in the 
state table is critical. Transitions are always scanned in the order 
in which they are entered, and the first transition matching a_ string 
being scanned is the transition taken. Therefore, the following order 
is recommended for states containing more than one syntax type: 


char 
keyword 
SEOS 
SALPHA 
SDIGIT 
SBLANK 
SNUMBR 
SDNUMB 
SSTRNG 
SRADS50 
SANY 
SLAMDA 


Placement of !label transitions in a state depends on the types. and 


positions of other syntax types in the state as well as on the syntax 
types in the starting state of the subexpression. 


7.2.2 Ignoring Blanks and Tabs in a Command Line 


Bit zero of the low byte of Register 1 (R1) controls processing of 
blanks and tab characters. If this bit is 1 when TPARS is invoked, 
blanks and tab characters are processed in the same way any other 
ASCII character is processed; they are treated as syntax elements 
that require validation by TPARS. If this bit is set to 0, blanks and 
tab characters are interpreted as terminator characters; they are 
ignored as syntax elements. In neither case does TPARS modify the 
command line. 


When blanks are being ignored, the S$BLANK syntax type never matches an 
element on the command line. Also, when this option is in effect, 
values returned to the !label syntax type by .PSTCN or .PSTPT may 
contain blanks or tabs, even though none were requested. The examples 
below show how TPARS parses the string: 


ABC DEF 


with and without the blank-Suppress option. 
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In the first example, an extra state is required to parse the blank: 


STATES 
TRANS - $STRNG 
STATES 
TRANS SBLANK 
STATES 
TRANS SSTRNG 


When TPARS is directed to ignore blanks and tab characters, the same 
string can be parsed using only two states: 


STATES 
TRANS SSTRNG 
STATES 
TRANS SSTRNG 


7.2.3 Entering Special Characters 


In “char" syntax elements, MACRO-11 interprets commas (,), semicolons 
(;), and angle brackets (< >) as special characters. The comma is 
interpreted as an argument separator and angle brackets are used _ to 
parenthesize special characters. 


To include a comma or a semicolon in a "char" syntax element string, 
use angle brackets: 


TRANS <',> 


Angle brackets cannot be passed as string elements in macro arguments. 
TE required in a "char" expression, they must be expressed 
symbolically, for example: 


LA = '< 
TRANS LA 


7.2.4 Recognition of Keywords 


When TPARS encounters a transition table entry that specifies a 
keyword, it first scans from the current point in the input string in 
search of a delimiter (nonalphanumeric) character. The characters 
between the current input point and the next delimiter are then 
assumed to be a possible keyword and are matched against the entries 
in the keyword table. For this reason, the following example will not 
work as expected: 


STATES 
TRANS "NO" ,STATE1,SETNEG 
TRANS S$LAMDA, ,SETPOS 


STATES STATE] 
TRANS "“AA",... 
TRANS "BB",... 
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When TPARS encounters the keyword NO, it will scan and attempt to 
match the string "NOAA" or "NOBB". If exact matching is requested, 
neither the "NO" transition nor the "AA" transition will match. In 
addition, if keyword matching is limited to two characters, the "NO" 
transition will match but TPARS will skip past "NOAA" so that the "AA" 
transition can be taken. You can use the following example to achieve 
the desired operation: 


STATES 
TRANS !NONO, STATE1,SETNEG 
TRANS SLAMDA, ,SETPOS 


STATES STATE 
TRANS "AA" gees 
TRANS PBB ous 


STATES NONO 


TRANS 'N 
STATES 
TRANS 'O, SEXIT 


In this example, TPARS attempts to match the subexpression NONO to the 
"NO" prefix one character at ae time. This bypasses the keyword 
scanning of TPARS, allowing the input pointer to be left pointing at 
"AA" or "BB". If NONO fails, the input pointer will not be changed 
and the scan can continue by looking for "AA" or "BB". 


7.3 PSECTS GENERATED BY TPARS MACROS 

TPARS macros generate three PSECTs. Data associated with the STATES 
macro is stored in the PSECT SSTATE, whereas data associated with the 
TRANS macro is stored in PSECTs SKSTR and SKTAB. SKTAB contains 
addresses for each of the entries of the keyword syntax type. SKSTR 
contains the keyword entries separated by character code 377 (octal). 
Each state consists of its transition entries concatenated in the 
order in which they are specified. The state label, if specified, is 


equated to the address of the first transition in the state. Each 
transition consists of from one to six words, as follows: 


Type Extension 
Action Return Address 
Maskword Address 
Target State Label 


ZK-314-81 
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The type byte of the first word may contain the following values: 


SLAMDA = 300 

SNUMBR = 302 

SSTRNG = 304 

SBLANK = 306 

SSUBXP = 310 Used in the !label type. 
SEOS = 312 

SDNUMB = 314 

SRAD50 = 316 

SANY = 320 

SALPHA = 322 

SDIGIT = 324 

char = ASCII code for the specified character 
keyword = 200+n (See explanation below.) 


The value of keyword is 200+n, where n is an index into the keyword 
table. The keyword table is an array of pointers to keyword strings, 
which are stored in the PSECT $KSTR. Keyword strings in SKSTR are 
separated from each other by 377 (octal). 


Bits in the flags byte indicate whether parameters for the TRANS macro 
are specified: 


Bit Meaning 


Type extension is specified. 

Action routine label is specified. 

Target state label is specified. 

Maskword is specified. 

Maskword address is specified. 

Indicates last transition in the current state. 


wR WN eH © 


7.4 INVOKING TPARS 


You control execution of TPARS using the calling conventions and 
options described in this section. TPARS is invoked from within an 
executing program on an IAS or RSX-11M system by means of the 
instruction 


CALL - TPARS 


When a user-sSupplied debug routine is used for tracing a TPARS 
operation (see Section 7.1.3.4), a special entry point is called, as 
follows: 


CALL - TPARD 


When TPARS is called in this manner, TPARS calls the debug routine at 
each state transition. If TPARS is invoked by means of the .TPARS 
entry point, the debug routine entry point address in .TPDEB is 
cleared and the debug routine is not called. 


THE TABLE-DRIVEN PARSER (TPARS) 


7.4.1 Register Usage and Calling Conventions 


When TPARS is invoked, registers in the calling program must contain 
the following information: 


Rl = Options word 

R2 = Pointer to the keyword table 

R3 = Length of the string to be parsed 

R4 = Address of the string to be parsed 

R5 = Label of the starting state in the state table 


On return from TPARS processing, registers contain the following 
information: 


R3 
R4 


Length of the unscanned portion of the string 
Address of the unscanned portion of the string 


The values of all other registers are preserved. 


The carry bit in the Processor Status Word returns 0 for a_ successful 
parse; the carry bit is set when TPARS finds a syntax error. 


For an example of a calling sequence for TPARS, refer to Section 
7.6.1. 


7.4.2 Using the Options Word 


The low byte of the options word contains flag bits. The only flag 
bit defined is bit zero, which controls processing of blanks. If bit 
zero is set to 1, blanks are interpreted as syntax elements. If bit 
zero is set to 0, blanks are ignored as syntax elements. 


The high byte of the options word controls abbreviation of keywords. 
If the high byte is set to 0, keywords being parsed must exactly match 
their corresponding entries in the state table. If the high byte is 
set to a number, keywords being parsed may be abbreviated to that 
number of characters. Keywords in the string that are longer than the 


Beg 
number specified must be spelled correctly up te the length specified 


by the number. 


TPARS clears the carry bit in the Processor Status Word when it 
completes processing successfully. This occurs when a transition is 
made to S$EXIT that is not within a subexpression. 


If a syntax error occurs, TPARS sets the carry bit in the Processor 
Status Word and terminates. 


A syntax error occurs when there are no syntax elements in the current 
state that match the portion of the string being scanned. Illegal 
type codes and errors in the state table can also cause a= syntax 
error. 


TPARS processing requires that the addresses in the state table and 
the keyword tables be reliable; bad addresses may cause program 
termination. 


The only syntax types that can match the end of the string are SEOS 
and S$LAMDA. 
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PARSER.SRC 


MCALL ISTAT$ 


1. Write a source program that | MCALL STATE$ 
EDI -.SS> > includes the required MCALL > MCALL TRANS 
statements. STATES 
STATES 


PARSER.OBJ 
MACRO-11 


{_______ 2. Assemble the source program to = > 
PADCED car produce an object module. 
1 woe 1s] w 


PARSER.OBJ 


MYFILE.TSK 


3. Execute the Task Builder to = 
MYFILE.OBJ produce a task image including 


the parser. 


UPDATE.OBJ 


ZK-298-81 


Figure 7-1 Processing Steps Required to Generate a Parser 
Program Using TPARS 
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7.5 HOW TO GENERATE A PARSER PROGRAM USING TPARS 


There are three processes involved in generating a parser program 
uSing TPARS, as shown in Figure 7-1. The source program must contain 
MCALL statements for three macros: ISTATS, STATES, and TRANS. These 
three MCALL statements must precede the statements that comprise the 
state table and action routines. 


Assembling the source module produces an object module comprised of 
three PSECTs: SSTATE, SKTAB, and SKSTR. When the Task Builder 
executes, the task image produced is placed on an appropriate volume 
for future use. 


The assembly listing produced by the state table macros is not 
straightforward. The source language macros are designed for clarity 
and convenience in writing state tables; the object code is designed 
for compactness and processing convenience. As a result, the 
mechanism used to translate the source code to object code is not a 
Simple one. 


The binary output of the macros is delayed by one statement. Thus, if 
the listing of macro-generated binary code is enabled, the binary code 
appearing after a macro call is, in fact, the result of the preceding 
macro call. Error messages generated by macro calls are similarly 
delayed. This is the reason an additional STATES macro is required to 
terminate the state table. 


When the parser program is linked and is in task image form, it can be 
invoked from within an executing user program, as shown in Figure 7-2. 


CALL .TPARS Action 


Routines 


Executing User-defined TPARS 
User Program Parser Program Processor 
| | aig STATES | a Scien a | | 
es l 
* mie. 
. 1 
! I 
STATES I 
| 
Fea ed eas i 3 
a | | 
aid I 
J 


2K-299-81 


Figure 7-2 Flow of Control When TPARS Is Called from an Executing 
User Program 


Figure 7-2 shows the CALL .TPARS statement that invokes the parser 
Program and the TPARS processor. As the parser executes the state 
table, it calls action routines. These action routines access code in 
the TPARS processor to perform such functions as returning the values 
of the built-in variables. When the state table completes execution, 
TPARS receives control and passes control back to the calling program. 
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7.6 PROGRAMMING EXAMPLES 


This section includes three programmed examples of how to use MTPARS. 
The first example shows the code required to parse a UFD command line 
for RSX-ll. The second example shows the use of subexpressions and 
how to reject transitions. The third example shows how to use 
subexpressions to parse indeterminate grammars. 


7.6.1 Parsing a UFD Command Line 
This example shows the code required to parse a UFD command line. It 
includes a state table and action routines. The general form of the 
UFD command line is as follows: 

UFD DKO: LABEL[201,202] /ALLOC=100./PRO=[RWED, RWED, RWE,R] 


The action routines in this parser program return the following 
values: 


SUDEV Device name (2 ASCII characters) 

SUUNIT Unit number (binary) 

SUVNML Byte count of the volume label string 
SUVNAM Address of the volume label string 

SUUIC Binary UIC for which to create a directory 
SUALL Number of directory entries to preallocate 
SUPRO Binary protection word for UFD 

SFLAGS Flags word containing the following bits: 
UF. ALL Set if allocation was specified. 

UF. PRO Set if protection was specified. 


The label and the /ALLOC and /PRO switches are optional. The calling 
sequence for this routine is as follows: 


CLR Rl 

MOV #UFDKTB,R2 
MOV COUNT, R3 
MOV ADDR,R4 
MOV #START,R5 
CALL - TPARS 

BCS ERROR 


The following is the user-written parser routine: 
-TITLE STATE TABLE FOR UFD COMMAND LINE 
-MCALL ISTATS,STATES, TRANS 
; TO BE USED WITH BLANK SUPPRESS OPTION 
ISTATS UFDSTB,UFDKTB 
; READ OVER COMMAND NAME 
~GLOBL START 


STATES START 
TRANS SUED" 


’ 


me 


me 


=e 


=e 
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READ DEVICE AND UNIT NUMBER 


STATES 
TRANS 


STATES 
TRANS 


STATES 
TRANS 
TRANS 


STATES 
TRANS 


READ VOLUME LABEL 
STATES 
TRANS 
TRANS 
READ UIC 


STATES 
TRANS 


SALPHA, ,SETDV1 


SALPHA, , SETDV2 


SNUMBR, DEV1,SETUNT 
SLAMDA 


DEV1 


te 
e 


SSTRNG, RUIC,SETLAB 
SLAMDA 


RUIC 
!UuIC 


SCAN FOR OPTIONS AND END OF LINE 


STATRS 
TRANS 
TRANS 


STATES 
TRANS 
TRANS 


STATES 
TRANS 


STATES 
TRANS 


PROTECTION 


STATES 
TRANS 


STATES 
TRANS 


STATES 
TRANS 
TRANS 
TRANS 
TRANS 
TRANS 
TRANS 


OPTS 
SEOS, SEXIT 
oF 


“ALLOC" ,ALC, ,UF.ALL, $FLAGS 
"PRO" ,PRO,,UF.PRO,$SFLAGS 


ALC 


SNUMBR, OPTS, SETALC 


PRO 


'L,,IGROUP 


SPRO 

'] ,OPTS, ENDGRP 
<',>,SPRO,NXGRP 
'R, SPRO, SETRP 
'w,SPRO, SETWP 
'E, SPRO, SETEP 
'D, SPRO, SETDP 


7-16 
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; SUBEXPRESSION TO READ AND STORE UIC 


STATE TABLE 


=o we TO 


SBTTL 
; DEVICE NAME 


SETDV1: :MOVB 


; DEVICE NAME 


SETDV2: :MOVB 


; UNIT NUMBER 


SETUNT: :MOV 


; VOLUME LABEL 


SETLAB: :MOV 


; PPN - GROUP 


SETGN:: 


TRANS an | 
STATES 
TRANS SNUMBR, ,SETGN 


TRANS <',> 


STATES 
TRANS SNUMBR, ,SETPN 


STATES 
TRANS SS) ZSEXIT 


STATES 


SIZE: 60 WORDS 


KEYWORD TABLE SIZE: 8 WORDS 
KEYWORD POINTER SPACE: 3 WORDS 


ACTION ROUTINES FOR THE COMMAND LINE PARSER 


CHAR 1 
.- PCHAR, SUDEV 
RETURN 
CHAR 2 
- PCHAR, SUDEV+1 
RETURN 
- PNUMB, SUUNIT 
RETURN 
- PSTCN, SUVNML 
MOV - PSTPT, SUVNAM 
RETURN 
NUMBER 
MOVB - PNUMB, SUUIC+1 
BR TSTPPN 


; PPN - PROGRAMMER NUMBER 


SETPN:: 
TSTPPN: 


10S: 
20S: 


MOVB . PNUMB, SUUIC 

TST . PNUMH ; CHECK FOR ZERO HIGH ORDER 

BNE 10$ 

TSTB . PNUMB+1 ; CHECK FOR BYTE VALUE 

BEQ 20$ 

ADD #2,(SP) ; BAD VALUE - REJECT TRANSITION 
RETURN 
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; NUMBER OF ENTRIES TO ALLOCATE 


SETALC: :MOV . PNUMB, SUALL 
RETURN 


; SET PERMISSIONS 
; INITIALIZE 


IGROUP: :MOV #4,GRCNT 


; MOVE TO NEXT PERMISSIONS CATEGORY 


NXGRP:: SEC ; FORCE ONES 

ROR SUPRO 

ASR SUPRO ; SHIFT TO NEXT GROUP 

ASR SUPRO 

ASR SUPRO 

DEC GRCNT ; COUNT GROUPS 

BGE 30$ ; TOO MANY IS AN ERROR 
BADGRP: ADD #2, (SP) ; IF SO, REJECT TRANSITION 
308: RETURN 


; SET READ PERMIT 


SETRP: : BIC #FP.RDV*10000,SUPRO 
RETURN 


: SET WRITE PERMIT 


SETWP:: BIC #FP.WRV*10000,SUPRO 
RETURN 


; SET EXTEND PERMIT 


SETEPS.: BIC FFP. EXT*10000,SUPRO 
RETURN 


; SET DELETE PERMIT 


SETDP:: BIC #FP.DEL*10000,SUPRO 
RETURN 
; END OF PROTECTION SPEC 
ENDGRP: : TST GRCNT ; CHECK THE GROUP COUNT 
BNE BADGRP ; MUST HAVE 4 
RETURN 
- END UFD 


7.6.2 How to Use Subexpressions and Reject Transitions 


This example is an excerpt of a state table that parses a_ string 
quoted by an arbitrary character. That is, the first character is 
interpreted as a quote character. This typical construction occurs in 
many editors and programming languages. The action routines 
associated with the state table return the byte count and address of 
the string in the locations QSTC and QSTP. The quoting character is 
returned in location QCHAR. 
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MAIN LEVEL STATE TABLE 


=e Me MO 


PICK UP THE QUOTE CHARACTER 


STATES STRING 
TRANS SANY, ,SETQ 


ACCEPT THE QUOTED STRING 


me 


STATES 
TRANS !QOSTRG, ,SETST 


GOBBLE UP THE TRAILING QUOTE CHARACTER 


=e 


STATES 
TRANS SANY,NEXT,RESET 


SUBEXPRESSION TO SCAN THE QUOTED STRING 
THE FIRST TRANSITION WILL MATCH UNTIL IT IS REJECTED 
BY THE ACTION ROUTINE 


se M6 MO 


STATES OQSTRG 

TRANS SANY, OSTRG, TESTQ 

TRANS SLAMDA, SEXIT 
ACTION ROUTINES 


STORE THE QUOTING CHARACTER 


SETQ: MOVB - PCHAR, QCHAR 
INCB - PFLAG ; TURN OFF SPACE FLUSH 
RETURN 


; TEST FOR QUOTING CHARACTER IN THE STRING 


TESTO: CMPB . PCHAR, OQCHAR 
BNE 10$ 
ADD #2, (SP) ; REJECT TRANSITION ON MATCH 
10S: RETURN 
; STORE THE STRING DESCRIPTOR 
SETST: MOV .PSTPT,QSTP 
MOV .PSTCN,QSTC 
RETURN 


; RESET THE SPACE FLUSH FLAG 


RESET: DECB - PFLAG 
RETURN 


7.6.3 Using Subexpressions to Parse Complex Grammars 


This example is an excerpt from a state table that shows how 
subexpressions are used to parse complex grammars. 


The state table accepts a number followed by a keyword qualifier. 


Depending on the keyword, the number is interpreted as either octal or 
decimal. 


7719 
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The binary value of the number is returned in the tagged NUMBER. The 
following types of strings are accepted: 


10/O0CTAL 
359/DECIMAL 
77777 /OCTAL 


; MAIN STATE TABLE ENTRY ~ ACCEPT THE EXPRESSION AND 
; STORE ITS VALUE 


STATES 
TRANS !ONUMB, NEXT, SETNUM 
TRANS !1DNUMB, NEXT, SETNUM 


; SUBEXPRESSION TO ACCEPT OCTAL NUMBER 


STATES ONUMB 
TRANS SNUMBR 


STATES 
TRANS wa 


STATES 
TRANS "OCTAL" ,SEXIT 


: SUBEXPRESSION TO ACCEPT DECIMAL NUMBER 


STATES DNUMB 
TRANS SDNUMB 


STATES 
TRANS '/ 


STATES 
TRANS "DECIMAL" ,SEXIT 


; ACTION ROUTINE TO STORE THE NUMBER 


SETNUM : MOV - PNUMB, NUMBER 
MOV - PNUMH, NUMBER+2 
RETURN 


The contents of .PNUMB and .PNUMH remain undisturbed by all_ state 
transitions except the SNUMBR and SDNUMB types. 


Because of the way in which subexpressions are processed, calls to 
action routines from within subexpressions must be handled with care. 


When a subexpression is encountered in a transition, TPARS saves its 
current context and calls itself, using the label of the subexpression 
as the starting state. If the subexpression parses successfully and 
returns by means of SEXIT, the transition is taken and control passes 
to the next state. 


If the subexpression encounters a syntax error, TPARS restores’ the 
saved context and tries to take the next transition in the state. 


However, TPARS provides no means for resetting original values changed 
by action routines called by subexpressions. Therefore, action 
routines called from subexpressions should store results in an 
intermediate area. Data in this intermediate area can _ then be 
accessed by an action routine called from the primary level of the 
State table. 


CHAPTER 8 


SPOOLING 


FCS provides facilities at both the macro and _ subroutine level _ to 
queue files for subsequent printing. 


8.1 PRINT$ MACRO CALL 

A task issues the PRINTS macro call to queve a file for printing on a 
specified device. The specified device must be a unit record, 
carriage-controlled device such as a line printer or terminal. If the 
device is not specified, LP: is used. 

The file to be spooled must be open when the PRINTS macro is issued. 
PRINTS closes the file. Error returns differ from normal FCS 
conventions and are described in Section 8.3. 


The PRINTS macro call nas the following format: 


PRINTS fdb,err,,dev,unit,pri,forms,copies,presrv 


f£db 
The address of the associated FDB. 
err 


The address of an optional, usSer-coded error-handling routine. 
See Section 8.3. 


The following parameters are not applicable to RSX-11M/M-PLUS. 


A blank parameter is present between err and dev, thus’ requiring an 
additional comma. 


dev 
The 2-character device mnemonic of the device on which the file 
is to be printed. If dev is not specified, LP: is used by 
default. 
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unit 


The unit number of the device on which the file is to be printed. 
If unit is not specified, unit 0 is used by default. 


pri 


A number in the range 1 through 250 to indicate the priority of 
the request. The priority is used to determine the order in 
which spooled files are dequeued for printing. If pri is 
omitted, the task's priority is used by default. 


forms 


The specific form-type on which the file is to be printed, as 
indicated by a number in the range 0 through 6. This parameter 
must be specified as a single integer without a preceding number 
Sign (#). The numbers) 0 through 6 are associated with the 
various forms for an installation by the system manager. If 
forms is omitted, form-type 0 is used by default. 


copies 


A number in the range 1 through 32(decimal) to indicate the 
number of copies of the file to be produced. The number of 


conies must he specified as a l- cr 2-digit 


integer without a 
preceding number sign (#). If copies is omitted, one copy is 
printed. If copies is specified as a decimal number, a_ trailing 


decimal point should be included in the parameter. 


presrv 


Should be specified if the file is not to be deleted after it is 
printed. Any parameter value results in the file's being 
preserved after printing. 


8.2 .PRINT SUBROUTINE 


The .PRINT subroutine is called to queue a file for printing. The 
file must be open when .PRINT is called, and then the .PRINT routine 
closes the file. RO must contain the address of the associated FDB. 
One copy of the file is printed on LP:. 


Section 8.3 describes error handling for the .PRINT file control 
routine. 


8.3 ERROR HANDLING 


The error returns provided in conjunction with PRINT$ and .PRINT 
differ from the standard FCS error returns in that error codes are 
placed in F.ERR or in the directive status word, depending on when the 
failure occurred. 


SPOOLING 


If the failure is FCS related (for example, the PRINTS macro cannot 
close the file), the C-bit is set and F.ERR contains the error code. 
If the failure is related to the SEND/REQUEST directive that queues 
the file, the C-bit is set and the directive status word contains an 
error code. Directive status word error codes are provided in the 
Executive Reference Manual of the host operating system. 


Normally, user-coded error routines, upon determining that the C-bit 
is set, should test F.ERR first and then test the directive status 


word. 


APPENDIX A 


FILE DESCRIPTOR BLOCK 


A File Descriptor Block (FDB) contains file information that is used 
by FCS and the file control primitives. The layout of an FDB is 
illustrated in Figure A-l. Table A-1 defines the offset locations 
within the FDB. 


The offset names in the file descriptor block may be defined either 
locally or globally, as shown below: 


FDOFSL ;DEFINE OFFSETS LOCALLY. 

FDOFFS$ DEFSL ;DEFINE OFFSETS LOCALLY. 

FDOFF$ DEFSG ;DEFINE OFFSETS GLOBALLY. 
NOTE 


When you refer to FDB locations, it is 
essential to use the symbolic offset 
names, rather than the actual address of 
such locations. The position of 
information within the FDB may be 
subject to change from release to 
release, whereas the offset names remain 
constant. 


FILE DESCRIPTOR BLOCK 


File-Attribute Section 


Record— or Block-Access 
Section 


File-Open Section 


Block-Buffer Section 


Figure A-l 


F.NRBD or 


F.BKST and F.BKDN 


F.OVBS or F.NREC 
F.EOBB 


F.RCNM or 
F.CNTG and F.STBK 


| F.VBSZ | 


ZK-300-81 


File Descriptor Block Format 


FILE DESCRIPTOR BLOCK 


Table A-1 
FDB Offset Definitions 


Offset Size Contents 
{in bytes) 


Record-type byte. This byte is set, as 
follows, to indicate the type of records for 
the file: 


| | F.RTYP = 1 to indicate fixed-length 
records (R.FIX). 

F.RTYP = 2 to indicate variable-length 
records (R.VAR). 

F.RTYP = 3 to indicate Sequenced records 


(R.SEQ). 
F.RATT 1 Record attribute byte. Bits 0 through 3 are 
set to indicate recerd attributes, as 
follows: 


Bit 0 = 1 to indicate that the first byte 
of a record is to contain a FORTRAN 
carriage control character (FD.FTN); 
otherwise, it is 0. 


Bit 1 = 1 to indicate for a carriage 
control device that a line feed is to be 
performed before the line is printed and 
a carriage return is to be performed 
after the line is printed (FD.CR); 
otherwise, it is 0. 


Bit 2 is not used. 
Bit 3 = 1 to indicate that records cannot 
cross block boundaries (FD.BLK); 
otherwise, it is 0. 

F.RSIZ 2 


Record-sSize word. This location contains 
the size of fixed-length records ofr 
indicates the size of the largest record 
that currently exists in a file of 
variable-length records. 


F.HIBK Indicates the highest virtual block number 


allocated. 


F.EFBK Contains the end-of-file block number. 


The format of the block number is high-order 
word followed by low-order word. 


Indicates the first free byte in the last 
block, or the maximum block size _ for 
magnetic tape. 


(continued on next page) 


FILE DESCRIPTOR BLOCK 


Table A-l (Cont.) 
FDB Offset Definitions 


Size Contents 
(in bytes) 


F.RACC Record access byte. Bits 0O through 3 of 
this byte define the record access modes, as 
follows: 


Bit 0 = 1 to indicate READS/WRITES mode 
(FD. RWM) ; otherwise, it is 0 to 
indicate GETS/PUTS mode. 


Bit 1 = 1 to indicate random access mode 
(FD. RAN) for GETS/PUTS record I/0; 
otherwise, it is 0 to indicate sequential 
access mode. 


Bit 2 = 1 to indicate locate mode 
(FD.PLC) for GETS/PUTS record I/0; 
otherwise, it is 0 to indicate move mode. 


Bit 3 = 1 to indicate that PUTS operation 
in sequential mode does not truncate the 
file (FD.INS); otherwise, it OX to 


| indicate that PUTS operation in 
| 


sequential mode truncates the file. 
Device characteristics byte. Bits 0 through 


5 define the characteristics of the device 
associated with the file, as follows: 


Bit 0 = 1 to indicate a _record-oriented 
device (FD.REC), for example, a Teletype 
or line printer; a value of 0 indicates 
a block-oriented device, for example, a 
disk or DECtape. 


device (FD.CCL); otherwise, it is 0. 


Bit 2 = 1to indicate a teleprinter 
device (FD.TTY); otherwise, it is 0. 


(FD.DIR); otherwise, it is 0. 


Bit 4 = 1 to indicate a single directory 
device (FD.SDI). An MFD is used, but no 
UFDs are present. 


Bit 5 = 1 to indicate a_ block-oriented 
device that is inherently sequential in 
nature (FD.SQD), such aS magnetic’ tape. 
A record-oriented device is assumed to be 
sequential in nature; therefore, this 


| | bit is not set for such devices. | 


(continued on next page) 


| 
| 
Bit 1 = 1 to indicate a carriage control 


| 
Bit 3 = 1 to indicate a directory device 


FILE DESCRIPTOR BLOCK 


Table A-1l (Cont.) 
FDB Offset Definitions 


Offset Size Contents 


(in bytes) 


allocated when the file must be extended. A 
positive (+) value indicates contiguous 
extend, and a negative (-) value indicates 
noncontiguous extend. 


F.BKDS 4 Contains the block I/O buffer descriptor. 
or 
F.URBD Contains the user record buffer descriptor. 
| F.NRBD | 4 Contains the next record buffer descriptor., | 
or 
F.BKST 2 Contains the address of the I/O status block 
and for block I/O. 

F.BKDN 2 Contains the address of the AST service 
routine for block I/O. 

F.OVBS 2 Override biock buffer size. This field has 

| or | | meaning only before the file is opened. 
| : ; 

F.NREC 2 Contains the address of the next record in 
the block. 

F.EOBB 2 Contains a value defining the end-of-block 
buffer. 

i I 

F.RCNM 4 Contains the number of the record for random 

or access operations. 

F.CNTG 2 Contains a numeric value defining the number | 
of blocks to be allocated in creating a new 
file. This cell has meaning only before the 
file is opened. A value of 0 means leave 
the file empty; a positive value means 
allocate the specified number of blocks as a 
contiguous area and make the file 
contiguous; a negative value means allocate 
the specified number of blocks as a 
noncontiguous area and make the file 
noncontiguous. 

F.STBK 2 Contains the address of the statistics block 
in your program. 

F.ALOC 2 Contains the number of blocks to be 


Contains the logical unit number associated 
with the FDB. 


(continued on next page) 


FILE DESCRIPTOR BLOCK 


Table A-1l (Cont.) 
FDB Offset Definitions 


Offset Size Contents 
(in bytes) 
F.FACC 1 File access byte. This byte indicates the 
access privileges for a file, as summarized 
below: 


Bit 0 = 1if the file is accessed for 
read only (FA.RD). 


Bit 1= 1#if the file is accessed for 
writing (FA.WRT). 


Bit 2 = 1if the file is accessed for 
extending (FA.EXT). 


Bit 3 = 1 if a new file is being created 
(FA.CRE); otherwise, it is 0 to indicate 
an existing file. 


Bit 4 = 1 if the file is a temporary file 
(FA.TMP). 


Bit 5=1 if the 


t fi 
shared access (FA.SHR). 
Tf Bit 3 above is 0: 


Bit 6 = 1 if an existing file is being 
appended (FA.APD). 


Bit 6 =1 if not superseding an 
existing File at file-create time 
(FA.NSP). 


F.DSPT Contains the dataset-descriptor pointer. 


| 

If Bit 3 above is one (1): 

| 

F.DFNB 


Contains the default filename block pointer. 


F.BKEF 
or 
F.EFN 


Contains the block I/0 event flag. 


Contains the record I/0 event flag. 


F.BKP1 Contains bookkeeping bits for FCS internal 


control. 


Error return code byte. A negative value 
indicates an error condition. 


(continued on next page) 


FILE DESCRIPTOR BLOCK 


Table A-1l (Cont.) 
FDB Offset Definitions 


Offset Size Contents 
1 | (in bytes) |! 
_ 


F.ERR+1 Used in conjunction with F.ERR_= above. If 
F.ERR is negative, the following applies: 


F.ERR+1 = 0 to indicate that error code 
is an I/O error code (see IOERRS error 
codes in Appendix I). 


F.,ERR+1 = negative value to indicate that 
error code is a Directive Status Word 
error code (see DRERRS error codes in 
Appendix I). 


F.MBCT 1 Inaicates the number of buffers to be used 
for multiple buffering. 
| 
| 
F.MBC1 1 Indicates the actual number of buffers 


currently in use if the multibuffering 
version of FCS is in use. 


| 

| 

i Multibuffering flag word. Contains either | 
one of the multibuffering flags, as follows: | 
H 

| 


a] 


| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| Bit 1 = 1 #+#to indicate write-behind 
| 


I 
| 
| 
Bit O = ] to indicate read-ahead 
i (FD.RAH). 
(FD.WBH). 
F.BGBC 1 Big buffer block count in number of blocks 
if the big-buffer version of FCS is in use. 
Buffer offset for reading ANSI magnetic tape 
in record mode. 
F.VBSZ | 2 Device buffer size word. Contains the 
| virtual block size (in bytes). 
| . 
F.BBFS | 2 Indicates the block buffer size. 
F.BKVB | 4 Contains the virtual block number in the 
or | user program for block I/0. 
F.VBN | Contains the virtual block number. 


F.BDB Contains the address of the block buffer 
descriptor block. This location always 


contains a nonzero value if the file is open 
and 0 if the file is closed. 


(continued on next page) 


FILE DESCRIPTOR BLOCK 


Table A-1 (Cont.) 
FDB Offset Definitions 


Offset Size Contents 
(in bytes) 


F.SPDV Reserved for future use. 


F.SPUN Reserved for future uSe. 


F.CHR Volume characteristics byte. 


Bit 0 = 1 to indicate ANSI magnetic’ tape 
formats D or F. 


F.ACTL The low-order byte of this word indicates 
the number of retrieval pointers to be used 
for the file. 


The control bits are in the high-order byte 
and are defined as follows. 


ns 
biw 


— 1 


mA fur 
=" ok cu L 


n eeanl 
Zz Ww ae 
e taken from F.ACTL 


a 9 nan 
tv row 
° 


S i 
information is t b 


(FA.ENB). 


end of a magnetic tape volume set upon 
open or close. 


magnetic tape volume set to just past the 
most recently closed file when the next 


| 

Bit 12 = 0 to cause positioning to the 
I 

file is opened (FA.POS). 


| 
Bit 12 = 1 to cause positioning of a 
| 
| 


Bit ll = 1 to cause a magnetic tape voiume 
set to be rewound upon open or _ close 
(FA.RWD). 


Bit 9 = 1 to cause a file not to be locked 
if it is not properly closed when accessed 
for write (FA.DLK). 


Contains the sequence number for sequenced 
records. 


Defines the beginning address of the 
filename block portion of the FDB. 


The format of a filename block is illustrated in Figure 


APPENDIX B 


FILENAME BLOCK 


B-1] e 


offsets within the filename block are described in Table B-l. 


The offset names in a filename block may be defined either locally 


globally, as shown below: 


NBOFSL ;DEFINE OFFSETS LOCALLY. 
NBOFFS DEFSL ;DEFINE OFFSETS LOCALLY. 
NBOFFS DEFSG ;DEFINE OFFSETS GLOBALLY. 


NOTE 


When you are referring to filename block 
locations, it is essential to use the 
symbolic offset names, rather than the 
actual addresses of such locations. The 
position of information within the 
filename block may be subject to change 
from release to release, whereas’ the 
offset names remain constant. 


The 


or 


FILENAME BLOCK 


Table B-1l 
Filename Block Offset Definitions 


Size 

Offset (in Bytes) Contents 

N.FID 6 File identification field 

N.FNAM 6 File name field; specified as nine 
characters that are stored in Radix-50 
format 

N.FTYP 2 File type field; specified as three 
characters that are stored in Radix-50 
format 

N.FVER 2 File version number field (binary) 

N.STAT 2 Filename block status word (See bit 
definitions in Table B-2.) 

N.NEXT 2 Context for next .FIND operation 

N.DID 6 Directory identification field 

N.DVNM 2 ASCII device name field 

N.UNIT 2 Unit number field (binary) 


The bit definitions of the filename block status word (N.STAT) in the 
FDB and their significance are described in Table B-2. 


Symbols marked with an asterisk (*) in Table B-2 indicate bits that 
are set if the associated information is supplied through an ASCII 
dataset descriptor. 


NB. VER* 


NB.TYP* 
NB.NAM* 


NB.SVR 


NB.STP 


NB. SNM 


FILENAME BLOCK 


CUMULATIVE 
LENGTH IN 
BYTES (OCTAL) 


ZK-301-81 


Table B-2 
Filename Block Status Word (N.STAT) 


Value 
(in Octal) Meaning 


Set if explicit file version number 
specified 

Set if explicit file type is specified 
Set if explicit file name is specified 


Set if wildcard file version number 
specified 


Set if wildcard file type is specified 


. 


40 Set if wildcard file name is specified 


(continued on next page) 


FILENAME BLOCK 


Table B-2 (Cont.) 
Filename Block Status Word (N.STAT) 


Value 
(in Octal) Meaning 


NB.DIR* Set if explicit directory string (UIC) is 
specified 


NB.DEV* Set if explicit device name string is 


specified 


NB.SD1 Set if group portion of UIC contains 
wildcard specificationl 


NB.SD2 Set if owner portion of UIC contains 
wildcard specificationl 


NB.ANS Set if file name is in ANSI format. 


1. Although NB.SD1 and NB.SD2 are defined, they are not set or 
supported by FCS. 


Table B-3 
Filename Block Offset Definitions for ANSI Magnetic Tape 


Size 
Offset |(in Bytes) Definition 
N.FID 2 File identification field 
N.ANM1 12 First 12 bytes of ANSI file name string 


N.FVER File version number field (binary) 


N.STAT | Filename block status word (See bit definitions 
in Table B-2.) 


N.NEXT Context for next .FIND operation 


N.ANM2 Remainder of the ANSI file name string 


N.DVNM ASCII device name field 


N.UNIT Unit number field (binary) 


The bit definitions of the filename block status word (N.STAT) are 
shown in Table B-2. 


The filename block format for ANSI magnetic tape file names is’ shown 
in Figure B-2. 


FILENAME BLOCK 
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N.ANM1 
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Figure B-2 ANSI Filename Block Format 


APPENDIX C 


SUMMARY OF I/O-RELATED SYSTEM DIRECTIVES 


Table C-l contains a summary of the I/O-related system directives in 
alphabetical order for ready reference. The parameters that may be 
specified with a directive are also described in the order of their 
appearance in the directive. These directives are described in detail 
in the Executive Reference Manual of the host operating system. 


Table C-1 
Summary of I/O-Related System Directives 


Directive Function and Parameters 


Assigns a logical unit number to a physical device: 


lun Logical unit number 


dev = Physical device name (2 ASCII characters) 
unt = Physical device unit number 
GLUNS Fills a 6-word buffer with information about a 
physical unit: 
lun = Logical unit number 
buf = Address of a 6-word buffer in which the LUN 


information is to be stored 


Transfers an 80-byte MCR/PDS command line to the 
issuing task. No parameters are required in this 
directive. 


(continued on next page) 


SUMMARY OF I/O-RELATED SYSTEM DIRECTIVES 


Table C-1 (Cont.) 
Summary of I/O-Related System Directives 


Function and Parameters 


Places an I/O request in the device queue associated 
with the specified logical unit number: 


Directive 


fne 


I/O function code 
lun = Logical unit number 
efn = Event flag number 


pri = Priority of the request (IAS only) 


isb = Address of the I/O status block 


ast = Entry-point address of the AST service 
routine 


pri Parameter list in the form < Pl,...,P6> 


Receives a 13-word data block that has been queued 
(FIFO) by a send data directive (see SDATS and SDRQS 
below): 


tsk Name of the sending task. This field is 
ignored by RSX-ll. The tsk parameter is 
specified as a null value (,) in RSX-1l for 
compatibility with IAS (see the description 
of the RCVDS directive in the RSX-11M/M-PLUS 
Executive Reference Manual). 
| 
| 
| 
| 


buf = Address of the 15-word data buffe (2-word 
sending task name and i3-word data “Bioek)’. 


| 
RCVSS$ Receives a 13-word data block if queued by a 
send-data directive (see SDAT$ AND SDRQS below), or 
suspends task if no data is queued: 
tsk = Name of the sending task 


buf = Address of the 15-word data buffer (2-word 
sending task name and 13-word data block) 


This directive is not supported in RSX-1l. 
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SUMMARY OF I/O-RELATED SYSTEM DIRECTIVES 


Table C-1 (Cont.) 


Summary of I/0-Related System Directives 


tsk 


tsk 


efn 


—_ 
= 


receive; 
the receiving task: 


I 
| 
SDROS | Queues (FIFO) a 13-word block of data for a task to 
| 
, 
| 
i 
| 


Directive Function and Parameters 


RCVX$ Receives a 13-word data block if queued by a= send 
data directive (see SDATS and SDROQS below), or exits 
if data is not queued for the task: 


Name of the sending task. This field is 
ignored by RSX-li. The tsk parameter is 
specified as a null value (,) in RSX-11 for 
compatibility with IAS (see the description 


of the RCVXS directive in the RSX-11M/M-PLUS 


Executive Reference Manual) 
Address of the 15-word data buffer (2-word 
sending task name and 13-word data block). 
SDATS Queues (FIFO) a 13-word block of data 
for a task to receive: 

tsk = Name of the receiving task 


buf = Address of the 13-word data buffer 


efn = Event flag number 


also requests or resumes the execution of 


Name of the receiving task 

Partition name of the receiving task 
Priority of the request 

UIC group code 

UIC owner code 

Address of the 13-word data buffer 


Event flag number 


| 


| This directive is not supported in RSX-1ll. | 


APPENDIX D 


SAMPLE PROGRAMS 


The sample programs that follow read records from an input device, 
strip off any blanks to the right of the data portion of the record, 
and write the data record on an output device. While the programs are 
intended primarily for card reader input and printer output, device 
independence is maintained. 


The main program is CRCOPY; CRCOPA and CRCOPB are variations. CRCOPA 
uses a dataset descriptor instead of the default filename block used 
in CRCOPY. CRCOPB uses run-time initialization of the FDB. 


-TITLE CRCOPY ;CARD READER COPY ROUTINE 
-MCALL FDBDFS,FDATSA,FDRCSA,FDOPSA,NMBLKS,FSRSZ$ 
-MCALL OPENSR,OPENSW,GETS,PUTS,CLOSES,EXITSS 
-MCALL FINITS 


INLUN=3 ;ASSIGN CR OR FILE DEVICE 
OUTLUN=4 :ASSIGN TO OUTPUT DEVICE 
FSRSZ$ 2 
FDBOUT: FDBDFS ;ALLOCATE SPACE FOR OUTPUT FDB 
FDATSA R.VAR,FD.CR ;INIT FILE ATTRIBUTES 
FDRCSA_ ,RECBUF,80. ; INIT RECORD ATTRIBUTES 
FDOPSA OUTLUN, ,OFNAM ;INIT FILE OPEN SECTION 
FDBIN: FDBDFS ;ALLOCATE SPACE FOR INPUT FDB 
FDRCSA_ ,RECBUF,80. ;INIT RECORD ATTRIBUTES 
FDOPSA INLUN,,IFNAM ;INIT FILE OPEN SECTION 
RECBUF: .BLKB 80. ;RECORD BUFFER 
OFNAM: NMBLKS OUTPUT,DAT ;OUTPUT FILENAME 
IFNAM: NMBLKS INPUT,DAT ; INPUT FILENAME 
START: FINITS ; INIT FILE STORAGE REGION 
OPENSR #FDBIN ;OPEN THE INPUT FILE 
BCS ERROR ;BRANCH IF ERROR 
OPENSW #FDBOUT ;OPEN THE OUTPUT FILE 
BCS ERROR ;BRANCH IF ERROR 
GTREC: GETS #FDBIN ;NOTE - URBD IS ALL SET UP 
BCS CKEOF ;ERROR SHOULD BE EOF INDICATION 
MOV F.NRBD(RO) ,R1 ;R1=SIZE OF RECORD READ 
MOV #RECBUF,R2 
ADD R1,R2 ;R2=ADDRESS OF LAST BYTE+1 
108: CMPB #40,-(R2) ;STRIP TRAILING BLANKS 
BNE PTREC 
SOB R1,10$ 


;AT THIS POINT, Rl CONTAINS THE STRIPPED SIZE OF THE 
;RECORD TO BE WRITTEN. IF THE CARD IS BLANK, 
7A ZERO-LENGTH RECORD IS WRITTEN. 


PTREC: PUTS #FDBOUT, ,R1 7;R1l IS NEEDED TO SPECIFY 
BCC GTREC ;THE RECORD SIZE. 
ERROR: NOP ;ERROR CODE GOES HERE 


CKEOF: CMPB 
BNE 
CLOSES 
BCS 
CLOSES 
BCS 
EXITSS 
. END 


- TITLE 
~MCALL 
-MCALL 
-MCALL 


INLUN=3 
OUTLUN=4 


FSRSZS$ 
FDBOUT: FDBDFS$ 
FDATSA 
FDRCSA 
FDOPSA 
FDBIN: FDBDFS 
FDRCSA 
FDOPSA 
RECBUF: .BLKB 
CFDSPT: .WORD 
.WORD 
«WORD 
IFDSPT: .WORD 
.WORD 
WORD 
ONAM: .ASCII 


SAMPLE PROGRAMS 


#IE.EOF,F.ERR(RO) ;END OF FILE? 


ERROR ;BRANCH IF OTHER ERROR 
RO ;CLOSE THE INPUT FILE 
ERROR 
#FDBOUT ;CLOSE THE OUTPUT FILE 
ERROR 

; ISSUE EXIT DIRECTIVE 
START 
CRCOPA CARD READER COPY ROUTINE 


FDBDF$,FDATSA,FDRCSA,FDOPSA,NMBLKS,FSRSZ$ 
OPENSR, OPENSW,GETS, PUTS, CLOSES, EXITSS 
FINITS 


;ASSIGN CR OR FILE DEVICE 
;ASSIGN TO OUTPUT DEVICE 

2 
R.VAR,FD.CR 
,RECBUF, 80. 
OUTLUN , OFDSPT 
,RECBUF, 80. 
INLUN, IFDSPT 
80. 
0,0 ;DEVICE DESCRIPTOR 
0,0 ;DIRECTORY DESCRIPTOR 
ONAMSZ , ONAM ;FILENAME DESCRIPTOR 
0,0 ;DEVICE DESCRIPTOR 
0,0 ;DIRECTORY DESCRIPTOR 
INAMSZ, INAM ;FILENAME DESCRIPTOR 
/OUTPUT. DAT/ 


ONAMSZ=.—-ONAM 


- EVEN 
INAM : -ASCIT 


/ INPUT. DAT/ 


INAMSZ=.—-INAM 


- EVEN 
START: FINITS 
OPENSR 
BCS 
OPENSW 
BCS 
GTREC: GETS 
BCS 
MOV 
MOV 
ADD 
108: CMPB 
BNE 
SOB 
;AT THIS POINT, 


; INIT FILE STORAGE REGION 


wea rit Pn to ot eee —— = 


#EDBIN sOPEN THE INPUT FILE 

ERROR ;BRANCH IF ERROR 

#FDBOUT ;OPEN THE OUTPUT FILE 

ERROR ;BRANCH IF ERROR 

#FDBIN ;NOTE - URBD IS ALL SET UP 
CKEOF ;ERROR SHOULD BE EOF INDICATION 


F.NRBD(RO),R1  ;R1=SIZE OF RECORD READ 
#RECBUF , R2 


R1,R2 ;R2=ADDRESS OF LAST BYTE+1 
#40,-(R2) ;STRIP TRAILING BLANKS 
PTREC 

R1,10$ 


Rl CONTAINS THE STRIPPED SIZE OF THE 


;RECORD TO BE WRITTEN. IF THE CARD IS BLANK, 
;A ZERO-LENGTH RECORD IS WRITTEN. 


PTREC: PUTS 
BCC 

ERROR: NOP 

CKEOF: CMPB 
BNE 
CLOSES 
BCS 
CLOSES 
BCS 
EXITSS 
. END 


#FDBOUT, ,R1 ;R1 IS NEEDED TO SPECIFY 
GTREC ;THE RECORD SIZE. 

;ERROR CODE GOES HERE 
#IE.EOF,F.ERR(RO) ;END OF FILE? 


ERROR ;BRANCH IF OTHER ERROR 
RO ;CLOSE THE INPUT FILE 
ERROR 

#FDBOUT ;CLOSE THE OUTPUT FILE 
ERROR 


;ISSUE EXIT DIRECTIVE 
START 


“TETLE 
.~MCALL 
»MCALL 
.~MCALL 
INLUN=3 
OUTLUN=4 
FSRSZS$ 
FDBOUT: FDBDFS$ 
FDBIN: FDBDFS 
RECBUF: .BLKB 
CFDSPT: .WORD 
WORD 
- WORD 
IFDSPT: .WORD 
. WORD 
. WORD 
ONAM: - ASCII 
ONAMSZ=. 
. EVEN 
INAM: - ASCII 
INAMSZ=. 
. EVEN 
START: FINITS 
OPENSR 


BCS 
FDATSR 
OPENSW 
BCS 
GTREC: GETS 
BCS 
MOV 
MOV 
ADD 
10S: CMPB 
BNE 
SOB 
;AT THIS POINT, 


SAMPLE PROGRAMS 


CRCOPB ;CARD READER COPY ROUTINE 
FDBDFS, FDATSA, FDRCSA, FDOPSA, NMBLKS, FSRSZ$ 
OPENSR, OPENSW,GETS, PUTS, CLOSES, EXITSS 
FINITS, FDATSR 
;ASSIGN CR OR FILE DEVICE 
;ASSIGN TO OUTPUT DEVICE 


2 

80. 

0,0 ;DEVICE DESCRIPTOR 
0,0 ;DIRECTORY DESCRIPTOR 
ONAMSZ , ONAM ;FILENAME DESCRIPTOR 
0,0 ;DEVICE DESCRIPTOR 
0,0 ;DIRECTORY DESCRIPTO 
INAMSZ , INAM ;FILENAME DESCRIPTOR 
/OUTPUT. DAT/ 

-ONAM 

/INPUT.DAT/ 

-INAM 


; INIT FILE STORAGE REGION 
#FDBIN, #INLUN, #IFDSPT,,#RECBUF, #80. 

;RUNTIME INITIALIZATION 
ERROR ;BRANCH IF ERROR 
#FDBOUT, #R.VAR,#FD.CR ;RUNTIME INITIALIZATION 
RO, #OUTLUN, #OFDSPT, , #RECBUF, #80. 


ERROR 7BRANCH IF ERROR 
#FDBIN ;NOTE - URBD IS ALL SET UP 
CKEOF ;ERROR SHOULD BE EOF INDICATION 


F.NRBD(RO) ,R] ;R1=SIZE OF RECORD READ 
#RECBUF,R2 


R1,R2 ;R2=ADDRESS OF LAST BYTE+1 
#40,-(R2) ;STRIP TRAILING BLANKS 
PTREC 

R1,10$ 


Rl CONTAINS THE STRIPPED SIZE OF THE 


;RECORD TO BE WRITTEN. IF THE CARD IS BLANK, 
;A ZERO-LENGTH RECORD IS WRITTEN. 


PTREC: PUTS 
BCC 

ERROR: NOP 

CKEOF: CMPB 
BNE 
CLOSES 
BCS 
CLOSES 
BCS 
EXITSS 
. END 


#FDBOUT,,R1 7;Rl IS NEEDED TO SPECIFY 
GTREC ;THE RECORD SIZE. 

;ERROR CODE GOES HERE 
#IE.EOF,F.ERR(RO) ;END OF FILE? 


ERROR ;BRANCH IF OTHER ERROR 
RO ;CLOSE THE INPUT FILE 
ERROR 

#FDBOUT ;CLOSE THE OUTPUT FILE 
ERROR 


;ISSUE EXIT DIRECTIVE 
START 
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INDEX FILE FORMAT 


The index file ([0,0]INDEXF.SYS) of a FILES-1l volume consists of 
virtual blocks, starting with Virtual Block 1, the bootstrap block. 
Virtual Block 2 is the home block. The structure of an index file is 
shown below. 


Virtual Block Number Index File Element 

af Bootstrap block. 

2 Home block. 

3 Index file bit map (n blocks); 
the value of n is in the home 
block. 

3+n Index file header. 

3+n+1 Storage-map header. 

3+n+2 Bad-block file header. 

34+n+3 Master File Directory header. 

34+n+4 Checkpoint file header 

34+n+5 User file header 1. 

34+n+6 User file header 2. 

: User file header n. 


E.1 BOOTSTRAP BLOCK 


A disk that is structured for FILES-11 has a 256-word block, starting 
at physical block 0. This block contains either a bootstrap routine 
or a message to the operator stating that the volume does not contain 
a bootstrappable system. The bootstrap routine brings a core image 
into memory from a predefined location on the disk. In IAS, the core 
image is pointed to by a file header block in the index file. 
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E.2 HOME BLOCK 

The home block contains volume identification information that is 
formatted as shown in Table E-l. This block is located either in 
Logical Block 1 or at any even multiple of 256 blocks. 


The offset names in the home block may be defined either locally or 
globally, as shown below. 


HMBOF$ DEFSL ;DEFINES OFFSETS LOCALLY. 


HMBOF$ DEFSG ;DEFINES OFFSETS GLOBALLY. 


E.3 INDEX FILE BIT MAP 

The index file bit map controls the use of file header blocks in the 
index file. The bit map contains a bit for each file header block 
contained in the index file. The bit for a file header block is 
located by means of the file number of the file with which it is 
associated. The values of the bit map are as follows: 


0 - Indicates that the file header block is available. The file 
control primitives can use this block to create a file. 


1 - Indicates that the file header block is in use. This block 
has already been used to create a file. 


E.4 PREDEFINED FILE HEADER BLOCKS 
The first five file header blocks are described below. 
File Header Block Significance 


Index File Header This is the standard header associated 
with the index file. 


Storage Map File The storage map is a file that is used’ 

Header to control the assignment of disk blocks 
to files. 

Bad Block File The bad block file is a file that 

Header consists of unusable blocks (bad 


sectors) on the disk. 


Master File Directory This header block is associated with the 

Header Master File Directory for the disk. 
This directory contains entries for the 
index file, the storage map file, the 
bad block file, the Master File 
Directory (MFD), the checkpoint file, 
and all User File Directories (UFDs). 


Checkpoint File Header This block identifies the file that is 
used for the checkpoint areas for all 
checkpointable tasks. In RSX-1ll, a task 
can also have checkpoint space in the 
task image itself. 


The remainder of the index file consists of file header blocks’ for 
user files, as shown in the illustration at the beginning of this 
section. 
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Table E-1 
Home Block Format 


| Size | | | 
| (in bytes) | Content | Offset | 
| | 


Index bit map size H.IBSZ 


used) 


Location of index bit H.IBLB 
map 
| 2 | Maximum files allowed H. FMAX | 
| 2 Storage bit map cluster H.SBCL | 
factor 
2 Disk device type H.DVTY 
2 Structure level H. VLEV 
| 2s Volume name (12 ASCII H. VNAM | 
characters) 
4 Reserved 
2 Volume owner's UIC H. VOWN | 
2 Volume protection code H. VPRO | 
| | j 
| 2 Volume characteristics H. VCHA 
| 2 Default file protection H.DFPR 
| word | 
| 
| 6 Reserved -- | 
| 1 Default number of H.WISZ 
| retrieval pointers 
in a window 
1 Default number of H.FIEX 
blocks to extend files 
1 Number of entries in H.LRUC 
directory LRU 
| as | Available space | -- 
{ 
| 2 | Checksum of words 0-28 | H.CHK1 
| 14; | Creation date and time | H.VDAT | 
if | 
| | 
100. Volume header label (not -- 
| 
| 


System specific infor- 
mation (not used) 


Relative volume table 


(not used) 


Checksum of home block H.CHK2 
(Words 0 through 255) 
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FILE HEADER BLOCK FORMAT 


Table F-1 shows the format of the file header block. The various 
areas within the file header block are described in detail in the 
following sections. The offset names in the file header block may be 
defined either locally or globally, as shown in the _ following 
statements: 


FHDOF$ DEFSL ;DEFINE OFFSETS LOCALLY. 
FHDOF$ DEFSG ;DEFINE OFFSETS GLOBALLY. 
Table F-l 


File Header Block 


Offset 


Size Content 


(in Bytes) 


Identification area offset H.IDOF | 
in words 
i Map area offset in words H.MPOF-. 
2 File number H. FNUM 
2 File sequence number H.FSEQ 
Z Structure level and system H.FLEV 
number 
- Offset to file owner H. FOWN 
information, consisting of 
member number and group 
number 
i Member number H. PROG 
Group number H. PROJ 


File protection code H.FPRO 


H.UCHA 


User-controlled file 
characteristics 


(continued on next page) 
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Table F-1 (Cont.) 
File Header Block 


Area Size Content Offset 
(in Bytes) 
1 System-controlled file H.SCHA 
characteristics 
32: User file attributes H.UFAT 
- Size in bytes of header S. HDHD 


area of file header block 


Identification 6 File name (Radix-50) I. FNAM 
Area 
2 File type (Radix-50) I. FTYP 
2 File version number I. FVER 
(binary) 
2 Revision number I.RVNO 
7 Revision date I.RVDT 
6 Revision time I. RVTI 
7 Creation date I.CRDT 
6 Creation time I.CRTI 
7 Expiration date Leo) 48 va 
1 To round up to word 
boundary 
| - | Size (in bytes) of | S.IDHD | 
| | identification area of | 
file header block 
Map Area Extension segment number M.ESON 


Extension relative volume  M.ERVN 


number (not implemented) 


Extension file number M.EFNU 


Extension file sequence 
number 


M.EFSQ 


Size (in bytes) of the 
block count field of a 
retrieval pointer (1 or 2); 
only 1 is used 


M.CTSZ 


(continued on next page) 
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Table F-1 (Cont.) 
File Header Block 


Area Size Content Offset 
' (in Bytes) | 
| 


Size (in bytes) of the M.LBSZ 
logical block number field 

of a retrieval pointer (2, 

3, or 4); only 3 is used 


| | a Words of retrieval pointers | M.USE 
in use in the map area 


1 Maximum number of words M.MAX 
of retrieval pointers 
available in the map area 

- Start of retrieval pointers M.RTRV 


- Size in bytes of map area S.MPHD 
of file header block 


Checksum Word Checksum of words 0 through H.CKSM 
255 


NOTE 


The checksum word is the last word of 
the file header block. Retrieval 
pointers occupy the space from the _ end 
of the map area to the checksum word. 


F.1 HEADER AREA 


The information in the header area of the file header block consists 
of the following: 


Identification area Word 0, Bits 0-7. This byte locates the start 

offset of the identification area relative to the 
start of the file header block. This offset 
contains the number of words from the start of 
the header to the identification area. 


Map area offset - Word 0, Bits 8-15. This byte locates the start 
of the map area relative to the start of the 
file header block. This offset contains’ the 
number of words from the start of the header 
area to the map area. 


File number - The file number defines the position this file 
header block occupies in the index file; for 
example, the index file is number 1, the 
storage bit map is file number 2, and so forth. 


File sequence number 


The file number and the file sequence number 
constitute the file identification number used 
by the system. This number is different each 
time a header is reused. 
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Structure level - This word identifies the system that created 
the file and indicates the file structure. A 
value of [1,1] is associated with all current 
FILES-11 volumes. 


File owner - This word contains the group number and owner 

information number constituting the User Identification 
Code (UIC) for the file. Legal UICs are within 
the range [1,1] to [377,377]. UIC: {lyi) ts 
reserved for the system. 


File protection code This word specifies the manner in which the 
file can be used and who can use it. When 
creating the file, you specify the extent of 


protection desired for the file. 


File characteristics 


This word, consisting of two bytes, defines the 
status of the file. 


Byte 0 defines the user-controlled characteris- 
tics, as follows: 


UC.CON = 200 - Logically contiguous file. 
When the file is extended (for example, by a 
WRITE or PUT), bit UC.CON is cleared whether 
or not the extension requests contiguous 
blocks. 


UC.DLK = 100 - File improperly closed. 


Byte 1 defines system-controlled characteris- 
tics, as follows: 


SC.MDL = 200 - File marked for delete 

SC.BAD = 100 - Bad data block in file 
User file - This area consists of 16 words. The first 
attributes seven words of this area are a direct image of 


the first seven words of the FDB when the file 
is opened. The other nine words of the’ record 
I/O control area are not used by FCS, although 
RMS does use them. 


F.2 IDENTIFICATION AREA 


The information in the identification area of the file header block 
consists of the following: 


File name - The file's creator specifies a file name of up 
to nine Radix-50 characters in length. This 
name is placed in the name field. The unused 
portion of the field (if any) is zero-filled. 


File type - This word contains the file type in Radix-50 
format. 

File version number - This word contains the file version number, in 
binary, as specified by the creator of the 
file. 
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Revision number - This word is initialized to 0 when the file is 
created; it is incremented each time a file is 
closed after being updated or modified. 


Revision date - Seven bytes are used to maintain the date on 
which the file was last revised. The revision 
date is kept in ASCII form in the format day, 
month, year (two bytes, three bytes, and two 
bytes, respectively). This date is meaningful 
only if the revision number is a nonzero value. 


Revision time - Six bytes are used to record the time at which 
the file was last revised. This information is 
recorded in ASCII form in the format hour, 
minute, and second (two bytes each). 


Creation date ~- The date on which the file was created is kept 
in a 7-byte field having the same format as 
that of the revision date (see above). 


Creation time - The time of the file's creation is maintained 
in a 6-byte field having the same format as 
that of the revision time (see above). 


Expiration date - The date on which the file becomes eligible to 
be deleted is kept in a 7-byte field having the 
same format as that of the revision date (see 
above). Use of expiration is not implemented. 


F.3 MAP AREA 


The map area contains the information necessary to map virtual block 
numbers to logical block numbers. This is done by means of pointers, 
each of which points to an area of contiguous blocks. A pointer 
consists of a count field and a number field. The count field defines 
the number of blocks contained in the contiguous area pointed to, and 
the logical block number (LBN) field defines the block number of the 
first logical block in the area. 


A value of n in the count field (see below) means that n+l blocks are 
allocated, starting at the specified block number. 


The retrieval pointer format used in the FILES-1l file structure is 
shown below: 


15 0 
COUNT-1 HIGH LBN 
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NOTE 


The remaining paragraphs in this 
appendix apply to IAS, and RSX-11 
systems that Support the multiheader 
version of FI11ACP. 


The map area normally has space for 102 retrieval pointers. It can 
map up to 102 discontiguous segments or up to 26112 blocks if the file 
is contiguous. If more retrieval pointers are required because the 
file is too large or consists of too many discontiguous segments, 
extension headers are allocated to hold additional retrieval pointers. 
Extension headers are allocated within the index file. They are 
identified by a file number and a file sequence as are other file 
headers; however, extension file headers do not appear in any 
directory. 


A nonzero value in the extension file number field of the map area 
indicates that an extension header exists. The extension header is 
identified by the extension file number and the extension file 
sequence number. The extension segment number is used to number the 
headers of the file sequentially, starting with a 0 for the first. 


Extension headers of a file contain a header area and identification 
area that are a copy of the first header as it appeared when the first 
extension was created. Extension headers are not updated when the 
first header of the file is modified. 


Extension headers are created and handled by the file control 
primitives as needed; their use is transparent to you. 
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SUPPORT OF ANSI MAGNETIC TAPE STANDARD 


This appendix defines the ANSI magnetic tape labeling standard, which 
is a level three implementation of the ANSI standard Magnetic Tape 
Labels and File Structure for Information Interchange (X3.27-1978). 
The only exception is that ANSI does not support spanned records. 


G.1 VOLUME AND FILE LABELS 


Tables G-l, G-2, and G-3 present the format of volume labels and file 
header labels. 


G.1.1 Volume Label Format 


Table G-l 
Volume Label Format 
Character Length 
Position Field Name (in Bytes) Contents 
1-3 Label identifier 3 VOL 
4 Label number 1 1 
5-10 Volume identifier 6 Volume label. Any ANSI "a" 
character. An "a" character 
is defined by the ANSI 
standard as any of the 
uppercase letters A’ through 
Z, the digits 0 through 9, 
and the following special 
characters: Space ! " % & 
'"O * +, -./3 s S=> 2 
ll Accessibility 1 Any ANSI "a" character. A 


space indicates no 
restriction. The /ACCESS = 
character switch to the INI 
command allows you to 
specify a character to be 
placed in this position. 
Any ANSI "a" character is 
permitted. The default 
character is a space. Refer 
to the RSX-11M/M-PLUS MCR 
Operations Manual for more 
information on INI. 


(continued on next page) 
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Table G-1l (Cont.) 
Volume Label Format 


Character Length 
Position Field Name (in Bytes) Contents 


Reserved Spaces. 


Owner The contents of this field 

identification are system dependent and are 
used for volume protection 
purposes. See Section 
G.1.1.1 below. 


Reserved Spaces. 


Label standard YY. 
version 


G.1.1.1 Contents of Owner Identification Field - The owner identifi- 
cation field is divided into the following three subfields and a 
single pad character: 

1. System identification (positions 38 through 40) 

2. Volume protection code (positions 41 through 44) 

3. UIC (positions 45 through 50) 


4. Pad character of one space (position 51) 


The system identification consists of the following character 
sequence: 


Dx 


The machine code, which can be one of the following: 


8 —- PDP-8 

A - DECsystem-10 
B - PDP-1l 

F - PDP-15 


The D%x characters provide an identification method so that the 
remaining data in the owner identification field can be interpreted. 
The /OWNER - switch to the INI command allows you to overwrite these 
characters. (Refer to the RSX-11M/M-PLUS MCR Operations Manual for 
more information.) In the case of tapes produced on PDP-ll systems, 
the default system identification is D%B and the volume protection 
code and UIC are interpreted as described below. 
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The volume protection code in positions 41 through 44 defines access 
protection for the volume for four classes of users. Each class of 
user has access privileges specified in one of the four columns, as 
follows: 


Position Class 
41 System (UIC no greater than [7,255]) 
42 Owner (group and member numbers match) 
43 Group (group number matches) 
44 World (any user not in one of the above) 


One of the following access codes can be specified for each character 
position: 


Code Privilege 


No access 

Read only 

Extend (append) access 
Read/fextend access 
Total access 


fm WN EF © 


The UIC is specified in character positions 45 through 50. The first 
three characters are the group code in decimal. The next three are 
the user code in decimal. 


The last character in the owner identification field is a space. 


The following is an example of the owner identification field. 
Owner identifier - D%B1410051102 ( indicates space) 


1. The file was created on a PDP-ll. 
2. System and group have read access. 
Owner has total access. 
All others are denied access. 


3. The UIC is [051,102]. 


G.1.2 User Volume Labels 


User volume labels are never written or passed back to you. If 
present, they are skipped. 


G.1.3 File Header Labels 


The following information should be kept in mind when creating file 
header labels. 


e The Files-1ll naming convention uses a subset (Radix-50) of the 
available ANSI character set for file identifiers. 


e One character in the file identifier, the period (.), is fixed 
by Files-1l. 


e A maximum of 13 of the 17 bytes in the file identifier are 
processed by Files-ll. 
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e It is strongly recommended that all file identifiers be 
limited to the Radix-50 PDP-1l character set, and that no 
character other than the period (.) be used in the file type 
delimiter position for data interchange between PDP-11 and 
DECsystem-10 systems. 


e For data interchange between DIGITAL and non-DIGITAL systems, 
the conventions listed above should be followed. If they are 
not, refer to Section G.1.3.1. 


Tables G-2 and G-3 describe the HDR1 and HDR2 labels, respectively. 


Table G-2 
File Header Label (HDR1) 


Label identifier 


followed by the name of the 
system that produced the 
volume. See Section 
Grisieis 

| 

| | Examples: DECFILE11A 
DECSYSTEM10 
| 


Pad name with spaces. 


Label number 1 
File identifier Any ANSI "a" character. See 
Table G-l. 
File set Volume identifier of the 
identifier first volume in the set of 
volumes. 
| 28-31 File section | 4 | Numeric characters. This | 
number | | field starts at 0001 and is | 
| | increased by 1 for each | 
additional volume used by 
the file. 
| | ' | j 
32-35 File sequence | 4 File number within the 
number volume set for this file. 
| This number starts at 0001. 
| 36-39 |Generation number | 4 | Numeric characters. | 
| | | | 
| | 
| 40-41 Generation version! 2 Numeric characters. 
| 
42-47 Creation date | 6 _yyddd (_ indicates space) 
or 
| _00000 if no date. 
48-53 Expiration date 6 Same format as creation 
date. 
54 Accessibility 1 Space. 
55-60 |Block count | 6 000000 
61-73 System code 13 The three letters DEC, 
| 


| 74 | Reserved | 7 | Spaces. | 


G-4 
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Table G-3 
File Header Format (HDR2) 


Character 


Position Field Name 


1-3 Label identifier | 

4 Label number 

5 Record format 

6-10 Block length 

11-15 Record length 

16-50 System-dependent 
information | 

51-52 Buffer offset 


Reserved 


(in Bytes) 


Length 


Contents 


Seen 

1 : 

1 F - Fixed length 
D - Variable length 
S - Spanned 
U - Undefined 

5 Numeric characters. 

5 Numeric characters. 

35 Positions 16 through 36 are 
ae 
Position 37 defines carriage 
control and can contain one 
of the following: 

A ~ First byte of 
record contains 
FORTRAN control 
characters. 

space - line 
feed/carriage 
return is to be 
inserted between 
records. 

M - the record 
contains all form 
control 
information. 

If DEC appears in positions 
61 through 63 of HDR1, 
position 37 must be as 
specified above. 
Positions 38 through 50 
contain spaces. 

2 Numeric characters. 00 on 


tapes produced by Files-ll. 
Supported only on input’ to 
Files-1ll. 


Spaces. 
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Table G-4 
File-Header Label (HDR3) 


Character Length 
Position Field Name (in Bytes) Contents 


Label identifier 


Label number 3 


System—dependent File attributes specified 
at creation time. Each 
of the 32 bytes of user 
file attributes is 
expanded into two 
hexadecimal characters. 


Reserved Spaces. 


G.1.3.1 File Identifier Processing by Files-1ll - The magnetic tape 
ACP processes Files-ll type file identifiers as described below. 
However, if the file name is enclosed in quotes, it is processed as an 
ANSI file name, all "a" characters are legal, all 17 positions may be 
used, and the only conversion that takes place is the upcasing of all 
lowercase characters and the conversion of aii characters that are not 
"a" characters to question marks. 


At file input, the file identifier is handled as follows: 


1. The first nine characters at a maximum are processed by an 
ASCII to Radix-50 converter. The conversion continues until 
one of the following occurs: 


a. A conversion failure. 


c. A period (.) is encountered. 


2. If the period is encountered, the next three characters after 
the period are converted and treated as the file type. If a 
failure occurs or all nine characters are converted, the next 
character is examined for a period. If it is a period, it is 
skipped and the next three characters are converted and 
treated as the file type. 


3. The version number is derived from the generation number and 
the generation version number as follows: 


(generation number - 1)*100 + generation version + 1 


If an invalid version number is computed, it will be changed 
to l. 
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At file output, the file identifier is handled as follows: 
1. The file name is placed in the first positions in the file 
identifier field. It can occupy up to nine positions and is 
followed by a period. 


2. The file type of up to three characters is placed after the 
period. The remaining spaces are padded with spaces. 


3. The version number is then placed in the generation and 
generation version number fields, as described in the 
following formulas: 


a. Generation number = (version # - 1) + z 
\ 100 


b. Generation version # = (version # — 1) Modulo 100 
NOTE 
In beth calculations, remainders are 


ignored. 


The following are examples. 


FILES-11 Version No. Generation No. Generation Version No. 
1. I 0 
50 1 49 
100 1 99 
101 2 0 
1010 1) 9 


G.1.4 End-of-Volume Labels 


End-of-volume labels are identical to the file header labels with the 
following exceptions: 


1. Character positions 1 through 4 contain EOV1 and EOV2 instead 
of HDR1 and HDR2, respectively. 


2. The block count field contains the number of records in the 
last file section on the volume. 


G.1.5 File Trailer Labels 


End-of-file labels (file trailer labels) are identical with file 
header labels, with the following exceptions: 


1. Columns 1 through 4 contain EOF1 and EOF2 instead of HDR1 and 
HDR2, respectively. 


2. The block count contains the number of data blocks in the 
file. 
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G.1.6 User File Labels 


User file labels are never written or passed back to you. If present, 
they are skipped. 


G.2 FILE STRUCTURES 

The file structures illustrated below are the types of file and volume 
combinations that the file processor produces. The file processor can 
read and process additional sequences. 


The minimum block size and fixed-length record size is 18 bytes. The 
maximum block size is 8192 bytes. 


If HDR2 is not present, the data type is assumed to be fixed (F), and 
the block size and record size are assumed to be the default value for 
the file processor. 512 decimal bytes is the default for both block 
and record size. You can override these defaults with the MAG command 
(see Section G.5). 


The meaning of graphics used in the file structure illustrations is as 
follows: 


1. The asterisk (*) indicates a tape mark. As defined by ANSI, 


a tape mark is a special control block recorded on magnetic 
tape to serve aS a separator between files and file labels. 


2. BOT indicates beginning of tape. 
3. EOT indicates end of tape. 


4. The comma (,) indicates the physical record delimiter. 


G.2.1 Single File Single Volume 


BOT, VOL1,HDR1,HDR2,HDR3*---DATA---*EOF1 , EOF2** 


G.2.2 Single File Multivolume 
BOT, VOL1,HDR1,HDR2,HDR3*---DATA---*EOV1 , EOV2** 


BOT, VOL1,HDR1,HDR2,HDR3*---DATA---*EOFI1 , EOF2** 


G.2.3 Multifile Single Volume 


BOT, VOL1,HDR1,HDR2, HDR3*---DATA---*EOF1 , EOF2*HDR1,HDR2, HDR3*---DATA 
--*EOF1 , EOF2** 


G.2.4 Multifile Multivolume 


BOT, VOL1,HDR1,HDR2,HDR3*--DATA--*EOFi, EOF2*HDRi,HDR2,HDR3*--DATA--* 
EOV1, EOV2** 


BOT, VOL1,HDR1,HDR2,HDR3*--DATA--*EOF1 , EOF2*HDR1,HDR2,HDR3*--DATA--* 
EOF] , EOQF2** 


G.3 END-OF-TAPE HANDLING 


End-of-tape is handled automatically by the magnetic tape file 
processor. Files are continued on the next volume provided that the 
volume is already mounted or mounted upon request. A request for’ the 
next volume is printed on CO: (console output pseudo-device). 


G.4 ANSI MAGNETIC TAPE FILE HEADER BLOCK (FCS COMPATIBLE) 


Figure G-1l illustrates the format of a file header block that is 
returned by the file header READ ATTRIBUTE command for ANSI magnetic 
tape. The header block is constructed by the magnetic tape primitive 
from data within the tape labels. 


MAP OFFSET IDENT OFFSET 


H.MPOF H.IDOF 
f FILE SEQUENCE NUMBER H.FNUM 
FILE SECTION NUMBER H.FSEO 


H.FOWN=H.PROG 
HEADER AREA 


H.FPRO 
H.UFAT 
RECORD SIZE IN BYTES 
N WORDS OF ZERO’S 
X+1.FNAM 
PIES NOME ADS? (IDENT OFFSET *2)=X 
FILE TYPE RAD50 |.FTYP 
FILE VERSION NUMBER X+LFVER 
ZERO’S (REVISION DATE & TIME) X+I.RVNO 
CREATION DATE & TIME (000000) X+1.CRDT 
IDENTIFICA- 
TION AREA EXPIRATION DATE X+1.EXDT 
PAD BYTE OF 0 X+47. 
COPY OF THE 
HDR1 LABEL Bee: 
COPY OF THE HDR2 LABEL 
(if byte 1 of label = 0, X+130. 
| label is not present) \ 
MAP AREA NULL-MAP, I.E. ee X+210.= 
ee BYTES LONG) (MAP OF OFFSET 2) 
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Figure G-l ANSI Magnetic Tape File Header Block (FCS Compatible) 
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G.5 THE MAGNETIC TAPE CONTROL TASK 

The Magnetic Tape Control Task (MAG) allows you to specify file 
attributes for unlabeled tapes, provides positioning functions for 
both unlabeled and ANSI tapes, and allows you to respond to requests 
for new tapes or volumes without mounting a new tape. 


This command can only be used on mounted tapes. The keywords are 
valid for both unlabeled and ANSI tapes, unless otherwise noted. 


The format of the MAG command is as follows: 


>MAG SET mmnn:/keyword[/keyword[s] ] 


Keywords: 
/BS=number-of-characters 
/CC=NONE 

LIST 

FORTRAN 
/EOF 
/EOT 
/EOV 
/INITIALIZE="volume id" 
/POS=number-of-files 


/RS=number-of-characters 


/ REWIND 


mmnn : 
Magnetic tape unit on which the operation is to be performed. 


Keyword definitions: 


BS /BS=number-of-bytes. Number of characters (bytes) 
per block on amounted tape. You can specify the 
number of characters in either decimal or octal. 
To specify a decimal number, terminate it with a 
period. The default is octal. 


This block size becomes the default for the tape. 
This value is used on output when there is no HDR2 
label present on an ANSI magnetic tape, and is used 
on output when no other value was specified on 
creation of the file. 


The value specified for block size must be greater 
than 14 (decimal) bytes. There is no maximum block 
size. 


See Section 1.3 for magnetic tape buffer sizes. 


SUPPORT OF ANSI MAGNETIC TAPE STANDARD 


CC /CC=type of carriage control. The default type of 
carriage control for the tape. Valid types of 
carriage control are as follows: 


NONE 
LIST 
FORTRAN 


When reading from an ANSI tape, this carriage 
control is used if: 


e No HDR2 label is present. 


e The HDR2~~ label contains a system 
identification other than DEC or OS. 


If a HDR2 label is present, the information in the 
HDR2 label is used and the /CC keyword is ignored. 


This keyword is the only way to specify carriage 
control for unlabeled tapes. 


EOF . /EOF. Causes the ACP to return the I/O status code 
IE.EOF to the requesting task. This keyword can be 
used to terminate a request for another tape in a 
volume set. 


This keyword is only valid for ANSI tapes. 


EOT 7EOT. Causes the ACP to return the I/O status code 
IE.EOT to the requesting task. This keyword can be 
used to terminate a request for another tape in a 
volume set. 


This keyword is only valid for ANSI tapes. 


EOV /EOV. Causes the ACP to return the I/O status code 
IE.EOV to the requesting task. This keyword can be 
used to terminate a request for another tape in a 
volume set. 


This keyword is only valid for ANSI tapes. 


INITIALIZE /INITIALIZE="volume id". The volume label to which 
the tape will be initialized. This keyword allows 
you to create a new volume to satisfy a request 
from the ACP for a new output volume for an ANSI 
tape. The format of the volume identifier is 
identical to the format of the volume identifier 
specified for the Mount command. Refer to the 
RSX-11M/M-PLUS MCR Operations Manual or _ the 
RSX-11M/M-PLUS Command Language Reference Manual 
for details. 


This keyword is only valid for ANSI tapes. 


POS /POS=number of files. The number of files (tape 
marks) to be spaced over from the current tape 
position. For example, /POS=0 means access’ the 
current file; /POS=l means space forward one file 
from the current position. The number of files may 
be specified in either decimal or octal. To 
specify a decimal number, terminate the number with 
a period. The default is octal. 
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The number of files specified must be between 0 and 
23417 (octal). 


This keyword is only valid for mounted unlabeled 
tapes. This keyword is not necessary for labeled 
tapes, since files can be accessed by name. 


If a tape containing ANSI or IBM labels is’ mounted 
as unlabeled, the formula to calculate the position 
of a data file is: 


N= (N-1)*3+1 
where N is the number of the desired file. 


RS /RS=number of characters. The number of characters 
per record for fixed-length records on tape. 


Maximum record size is the block size. 


When reading files from an ANSI tape, this value is 
used for record size when no HDR2 label is present. 


This keyword is the only way to specify record size 
for unlabeled tapes. 


REWIND /REWIND. Specifies that the tape is to be rewound 
to BOT. For ANSI tapes, this keyword rewinds to 


2 + reatee GS ss ~ xo wa on crm A n 
the beginning of tne volume set. 


Example: 


>MOU MMO: /NOLABEL/TR=EBCDIC 

>MAG SET MMO:/BS=80./RS=80./CC=LIST/REWIND 

>! Read the first "file" on the tape to determine the actual tape format 
>PIP TI:=MM0:X 

VOL1X234870 NASHUA 

HDRIDEC2.KP72132 X2348700010001 80256 802860000000IBM OS/VS 370 
HDR2F008000008030DEC 2K009/DEC2U009 B 60337 

>! This information shows that the tape in fact has labels that 

>! resemble ANSI labels (this tape is in the format of 

>! another computer manufacturer). The actual block size and record size 
>! can be determined from the labels. 

>! Use the MAG SET command to set the actual block and record size. 

>MAG SET MMO:/BS=800./RS=80. 

>! Use the MAG SET /POS command to positon to the next file on the tape 
>! You could also position to the file by specifying 

>! a position to PIP as follows: PIP TI:=MM0:"POS=R1" 

>! where R indicates Rewind and 1 is the number of tape 

>! marks to space over. 

>MAG SET MMO:/REWIND/POS=1 

>! Read the data file. Note that PIP requires a dummy file name, even 

>! though the tape is already positioned at the correct file. 

>PIP TI:=MM0:X 


001 321 03054 MERRIMACK 603 
002 456 03060 NASHUA 603 
003 789 02165 NEWTON 617 
004 124 01845 NORTH ANDOVER 617 
005 345 64801 JOPLIN 714 
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Command Error Messages: 


MAG -- Device not mounted or mounted foreign 
Explanation: Specified device must be either a mounted ANSI tape 
or a mounted unlabeled tape. A foreign tape that is mounted 
foreign is not known to the magnetic tape ACP and is therefore 
the same aS an unmounted tape. The MAG command only supports 
mounted tapes. 
User Action: Mount the device with the /NOLABEL qualifier if it 
is an unlabeled tape. Do not use the MAG command with tapes that 
are mounted foreign. 

MAG -- Get command line failure 


Explanation: An illegal indirect command file name was specified 
or MAG could not find the specified indirect command file. 


User Action: Check the specification for the indirect command 
file and reenter the command line. 
MAG -- Illegal combination of keywords 


Explanation: Keywords were specified that required both an 
unlabeled tape and an ANSI tape. 


User Action: Refer to the keyword descriptions in this chapter 
to determine which switches require ANSI tapes and which require 
unlabeled tapes. 


MAG -- Illegal file attributes combination 


Explanation: A record size was specified that was not less’ than 
or equal to the block size. 


User Action: Specify a record size less than or equal to the 
block size. 


MAG -- Illegal switch value 
Explanation: One of the following: 
e /POS value was greater than 9999. 
e /BS value was less than 14. 
e /RS value was less than 14. 


User Action: Determine which value was illegal and retype the 
command line. 


MAG -- Invalid device or unit 


Explanation: Specified device does not exist or is not a 
magnetic tape. 


User Action: Determine the correct device or unit and retype the 
command line. 
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MAG -- Operation is only valid for mounted ANSI tapes 


Explanation: An operation that is only valid for ANSI magnetic 
tape was attempted on an unlabeled tape. 


User Action: Use only valid commands. 


MAG ~-- Operation is only valid for unlabeled tapes 


Explanation: An operation that is only valid for unlabeled tapes 
was attempted on an ANSI tape. 


User Action: Use only valid commands. 


MAG -- Privilege violation 


Explanation: On systems with multiuser protection, only the 
terminal to which the tape drive is allocated may change the tape 
characteristics. 


User Action: Reenter the command from the terminal that owns the 
tape drive. 


MAG -- Requested operation inconsistent with tape state 
ons The user specified /EOF, /EOV, or /EOT and the 
tape ACP rejected it. 


The user specified /INITIALIZE and the ACP rejected it. 


User Action: Determine the state of the tape and type only 
commands that can be performed in the current state. 


Explanation: The command was specified incorrectly. 


User Action: Check the correct syntax as described in this 
chapter, and then reenter the command line. 


G.6 UNLABELED TAPE 


A tape that contains no labeling information is called an _ unlabeled 
tape. An unlabeled tape contains either blocked or _ unblocked 
fixed-length records. When a tape is mounted with the /NOLABEL 
qualifier on the MOUnt command, FCS and RMS can access records on the 
tape using standard read and write operations. This is different from 
mounting a tape foreign (MOU/FOREIGN). When a tape is mounted foreign 
(or not mounted at all on RSX-11M systems), records on the tape must 
be accessed directly using the QIO operations that are defined for the 
magnetic tape driver. 
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G.6.1 Tape Positioning 


Any tape motion before the first read operation must be explicitly 
requested in one of the foilowing ways: 


e The FA.ENB!FA.RWD bit may be set in F.ACTL to request a rewind 
of the volume set prior to create or find-file operations. 


e The MAG SET /POS command may be specified to space forward a 
specified number of files from 0 to 9999, 


e The MAG SET /REWIND command may be specified to rewind the 
tape to BOT. 


e The file may be referenced by the name "POS=[R][nnnn]"“ where R 
indicates that the tape is to be rewound, and nnnn is the 
number of files (tape marks) to space forward. For example, 
to read the second file on a tape: 


>PIP TI:=MM:"POS=0001" 


Each tape mark delimits a file. All positioning operations are in 
terms of tape marks. If any type of label is present on the tape, it 
will be treated as a file. 


When a file is deaccessed, position within the file is always 
consistent. 


G.6.2 Specifying File Attributes 


You can specify the attributes for files to be read from tape in three 
ways: 


1. The MOUnt command (see the RSX-1i1M/M-PLUS MCR Operations 
Reference Manuai or the RSX-1iM/M-PLUS Command Language 
Reference Manual). 


2. Any create operation request. You can issue the create 
request from within your program by creating a file and 
closing it without writing any data, or by using the RMS 
DEFINE utility. The FCS create routine returns the error 
code IE.BTP (bad record type) if an attempt is made to set 
the record type to anything other than fixed length. 


3. The MAG SET command (see Section G.5). 


G.6.3 Translation 


You can request translation for a tape at the time it is mounted (see 
the RSX-11M/M-PLUS MCR Operations Reference Manual or the 
RSX-11M/M-PLUS Command Language Reference Manual). If you have 
requested translation, your data buffer (the FCS or RMS block buffer) 
is translated within your task. Therefore, on a write operation, the 
data in your task is destroyed. 
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You can add up to three installation-dependent translation routines to 


the magnetic tape ACP by adding routines with the following format: 


USERn:: MOV #TBLPTR,RO zn is 1, 2, or 3. 


RETURN 


TBLPTR: .~WORD INTRAN 

eWORD OUTRAN 
INTRAN: <A 256 byte table for input translation> 
OUTRAN: <A 256 byte table for output translation> 


For example, the EBCDIC translation tables that are provided with your 
system are shown in section G.6.4. 


You must include these translation routines in the Overlay Description 
the magnetic tape ACP when the MTAACP task is 
built. Comments within the files MTABLD.ODL and MTABLD.CMD 
where these routines may be added. 


Language (ODL) for 


G.6.4 Example of EBCDIC Translation Tables 


EBCDIC:: MOV #TBLPTR, RO 
RETURN 

TBLPTR: .WORD EBCASC 
- WORD ASCEBC 
-NLIST BEX 

EBCASC: .BYTE 000,001,002,003,040,011,040,177,040,040 
- BYTE 040,013,014,015,016,017,020,021,022,023 
- BYTE 040,040,010,040,030,031,040,040,040,035 
- BYTE 040,037,040,040,034,040,040,012,027,033 
- BYTE 040,040,040,040,040,005,006,007,040,040 
- BYTE 026,040,040,036,040,004,040,040,040,040 
-BYTE 024,025,040,032,040,040,040,040,040,040 
BYTE 040,040,040,040,133,056,074,050,053,135 
~BYTE 046,040,040,040,040,040,040,040,040,046 
- BYTE 041,044,052,051,073,136,055,057,040,040 
. BYTE 040,040,040,040,040,040,174,054,045,137 
-BYTE 076,077,137,040,040,040,040,040,040,040 
«BYTE 040,140,072,043,100,047,075,042,040,141 
- BYTE 142,143,144,145,146,147,150,151,040,040 
- BYTE 040,040,040,040,040,152,153,154,155,156 
- BYTE 157,160,161,162,040,040,040,040,040,040 
- BYTE 040,176,163,164,165,166,167,170,171,172 
- BYTE 040,040,040,040,040,040,040,040,040,040 
- BYTE 040,040,040,040,040,040,040,040,040,040 
- BYTE 040,040,173,101,102,103,104,105,106,107 
-BYTE 110,111,040,040,040,040,040,040,175,112 
- BYTE 113,114,115,116,117,120,121,122,040,040 
-BYTE 040,040,040,040,134,040,123,124,125,126 
- BYTE 127,130,131,132,040,040,040,040,040,040 
- BYTE 060,061,062,063,064,065,066,067,070,071 
~ BYTE 040,040,040,040,040,040 


indicate 


=e 


=e 


50. 


100. 


150. 


200. 


250. 
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ASCEBC: .BYTE 000,001,002,003,067,055,056,057 
-BYTE 026,005,045,013,014,015,016,017 
- BYTE 020,021,022,023,074,075,062,046 
- BYTE 030,031,077,047,042,035,065,037 
~ BYTE 100,132,177,173,133,154,120,175 
.- BYTE 115,135,134,116,153,140,113,141 
- BYTE 360, 361,362,363,364, 365, 366,367 
BYTE 370,371,172,136,114,176,156,157 
~BYTE 174,301,302,303,304,305, 306,307 ; 100 
- BYTE 310,311,321,322,323,324,325,326 
-BYTE 327,330,331,342,343,344,345,346 
- BYTE 347,350,351,112,340,117,137,155 
-BYTE 171,201,202,203,204,205,206,207 
- BYTE 210,211,221,222,223,224,225,226 
- BYTE 227,230,231,242,243,244,245, 246 
- BYTE 247,250,251,300,152, 320,241,377 


40 


me 
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EXAMPLE USING AN INDIRECT COMMAND FILE TO READ A TAPE 


e~ ENABLE QUIET 

» ENABLE SUBSTITUTION 

-; This command file is invoked with the command 

: @MTA outspec=Mx:infile 

; and searches a tape mounted unlabeled (which has an ANSI-like structure) 
; for the file "“infile"™ and copies it to outspec. 
f 
i 
i 


Parse the command line; OUTSPC gets outspec, 
DEV gets Mx, 

: INFILE gets the file name to find on tape. 

-PARSE COMMAN “ " OUTSPC COMMAN 

-PARSE COMMAN "=" OUTSPC INSPEC 

«PARSE INSPEC ":" DEV INFILE 

-IF INFILE EQ "" .GOTO NOTMT 

»~SETS INFILE INFILE+" " 

e-SETS INFILE INFILE[1:17.] 

-SETS JUNK DEV[1:1] 

-IF JUNK NE "M" .GOTO NOTMT 

“fr 

-; Make a name for the temp file 

on 

~TESTFILE TI: 

-PARSE <FILSPC> ":" TMP JUNK 

~SETS TMP TMP+".TMP" 

en 

-; Always start at the beginning of the tape: 

MAG SET 'DEV':/REWIND 

aa 

-; Labels have a block and record size of 80. 

MAG SET 'DEV':/BS:80./RS:80. 

- LOOK: 

“7 

-; Put the labels in a temp file so INDirect can look at them 

PIP '"TMP'='DEV':DUMMY.NAM 

~OPENR ‘TMP! 

. READLB: 

~READ LABEL 

IFT <EOF> .GOTO NOSUCH 

»~SETS LABELT LABEL[1:3] 
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-; Skip any VOLume header labels 

IF LABELT = "VOL" .GOTO READLB 

.IF LABELT NE "HDR" .GOTO ILLFMT 

-SETS LABELT LABEL[4: 4] 

~IF LABELT NE "1" .GOTO ILLFMT 

~SETS LABELT LABEL[5:21.] 

on 

; If the names do not match, go get the next set of labels. 
IF LABELT NE INFILE .GOTO TRYNXT 
¢ 


-; We have found the file, see if there is a HDR2 with size info. 
«READ LABEL 

eIFT <EOF> .GOTO READFL 

-SETS LABELT LABEL[1: 4] 

~IF LABELT NE "HDR2" .GOTO READFL 
°¢ 

-; Yes, we have a HDR2 label. 
SETS LABELT LABEL[37.:37.] 

SETS CC "LI" 

IF LABELT = "A" .SETS CC "FO" 
IF LABELT = "M" .SETS CC "NO" 
-SETS BS LABEL[6:10.] 

~SETS RS LABEL[11.:15.] 


; Set up the Block Size, Record Size, and Carriage Control 
-; Based on what was in HDR2. 

MAG SET 'DEV':/BS:'BS'./RS:'RS'./CC:'CC' 

-SETS LABELT LABEL[5: 5] 

IF LABELT EQ "F" .GOTO READFL 

»~DISABLE QUIET 

iMTA - Warning, Record Format is ‘LABELT‘; only F Format is fully supported. 
«ENABLE QUIET 

» READFL: 

«CLOSE 

ov 

-; Transfer the file. 

PIP "OUTSPC'='"DEV':"POS=1" 

-GOTO ENDIT 

« TRYNXT: 

~ CLOSE 

MAG SET 'DEV':/POS=3 

-GOTO LOOK 

- ILLFMT: 

~DISABLE QUIET 

«DISABLE MCR 

MTA - Tape is not in a format that I understand. 
-GOTO ENDIT 

«NOTMT: 

-DISABLE QUIET 

~DISABLE MCR 

MTA - Input file spec must specify a Magtape device and a file name. 
«EXIT 

~NOSUCH: 

-~DISABLE QUIET 

«DISABLE MCR 

MTA - No such file -- 'INSPEC' 

-ENDIT: 

«ENABLE MCR 

» ENABLE QUIET 

PIP 'TMP'; /DE/NM 

EXIT = 
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STATISTICS BLOCK 


The format of the statistics block is shown in Figure H-1l below. The 
statistics block is allocated manually in your program as described in 
item 3.d of Section 3.1.2. 


Bee Nr ee ee OE 


(0 if file is noncontiguous) 


SIZE (high) 


SIZE (low) 


LOCK COUNT ACCESS COUNT 


ZK-304-81 


Figure H-l Statistics Block Format 
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ERROR CODES 


This appendix lists: 
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e 1/0 error codes 
e Directive Status Word error codes 


e I/0 function codes 


»-TITLE QIOMAC - QIOSYM MACRO DEFINITION 
DATE OF LAST MODIFICATION: 


John R. Covert 29-Jul-81 


-IDENT /0351/ 
QI.VER=0351 


COPYRIGHT (C) 1980 
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS. 


THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A 
SINGLE COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE 
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE, OR 
ANY OTHER COPIES THEREOF, MAY NOT BE PROVIDED OR OTHERWISE 
MADE AVAILABLE TO ANY OTHER PERSON EXCEPT FOR USE ON SUCH 
SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE TERMS. TITLE 
TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES REMAIN 
IN DEC. 


THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT 
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL 
EQUIPMENT CORPORATION. 

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF 
ITS SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC. 


PETER H. LIPMAN 11-OCT-73 
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ERROR CODES 


MACRO TO DEFINE STANDARD QUEUE I/O DIRECTIVE FUNCTION VALUES 
AND IOSB RETURN VALUES. TO INVOKE AT ASSEMBLY TIME (WITH LOCAL 
DEFINITION) USE: 

Qrosy$ ;DEFINE SYMBOLS 
TO OBTAIN GLOBAL DEFINITION OF THESE SYMBOLS USE: 

QIOSYS DEFSG ;SYMBOLS DEFINED GLOBALLY 
THE MACRO CAN BE CALLED ONCE ONLY AND THEN 
REDEFINES ITSELF AS NULL. 


-MACRO QIOSYS S$SSGBL,$S$SSMSG 


.IIF IDN,<SSSGBL>,<DEFSG>, -GLOBL QI.VER 

IF IDN,<SSSMSG>,<DEFSS> 

SSSMAX=0 

SSMSG=1 

.IFF 

$SMSG=0 

. ENDC 

~MCALL IOERRS 

IOERRS SSSGBL ;I1/0 ERROR CODES FROM HANDLERS, FCP, FCS 
~MCALL DRERRS 

DRERRS$S S$SSGBL ;DIRECTIVE STATUS WORD ERROR CODES 
IF DIF,<SSSMSG>,<DEFS$S> 

-MCALL FILIOS 

FILIOS S$SSGBL ;DEFINE GENERAL I/O FUNCTION CODES 
.MCALL spcros 

SPCIOS S$SSGBL ;DEVICE DEPENDENT I/O FUNCTION CODES 


~MACRO QIOSY$ ARG,ARG1,ARG2 ;RECLAIM MACRO STORAGE 
- ENDM QIOsys 

- ENDC 

- ENDM Qrosy$ 


DEFINE THE ERROR CODES RETURNED BY DEVICE HANDLER AND FILE PRIMITIVES 
IN THE FIRST WORD OF THE I/O STATUS BLOCK 

THESE CODES ARE ALSO RETURNED BY FILE CONTROL SERVICES (FCS) IN THE 
BYTE F.ERR IN THE FILE DESCRIPTOR BLOCK (FDB) 


THE BYTE F.ERR+1 IS 0 IF F.ERR CONTAINS A HANDLER OR FCP ERROR CODE. 


»~ENABL LC 


»-MACRO IOERRS SSSGBL 
-MCALL .IOER.,DEFINS 

IF IDN,<S$SGBL>,<DEFS$G> 
-. -GBL=1 

.IFF 

2» ~GBL=0 

.ENDC 

.IIF NDF, SSMSG, $SMSG=0 


ERROR CODES 


SYSTEM STANDARD CODES, USED BY EXECUTIVE AND DRIVERS 


me ue 


-IOER. IE.BAD,-01.,<Bad parameters> 

-IOER. IE.IFC,-02.,<Invalid function code> 

~IOER. IE.DNR,-03.,<Device not ready> 

-IOER. IE.VER,-04.,<Parity error on device> 

-IOER. IE.ONP,-05.,<Hardware option not present> 

-IOER. IE.SPC,-06.,<Illegal user buffer> 

-IOER. IE.DNA,-07.,<Device not attached> 

-IOER. IE.DAA,-08.,<Device already attached> 

»~IOER. IE.DUN,-09.,<Device not attachable> 

~IOER. IE.EOF,-10.,<End of file detected> 

~IOER. IE.EOV,-11.,<End of volume detected> 

-IOER. IE.WLK,-12.,<Write attempted to locked unit> 
-IOER. IE.DAO,-13.,<Data overrun> 

~IOER. IE.SRE,-14.,<Send/receive failure> 

~IOER. IE.ABO,-15.,<Request terminated> 

-IOER. IE.PRI,-16.,<Privilege violation> 

~IOER. IE.RSU,-17.,<Sharable resource in use> 

-IOER. IE.OVR,-18.,<Illegal overlay request> 

-IOER. IE.BYT,-19.,<Odd byte count (or virtual address) > 
-IOER. IE.BLK,-20.,<Logical block number too large> 
~IOER. IE.MOD,-21.,<Invalid UDC module #> 

eIOER. IE.CON,-22.,<UDC connect error> 

-IOER. IE.BBE,-56.,<Bad block on device> 

-IOER. IE.STK;-58.,<Not enough stack space (FCS or FCP)> 
~IOER. IE.FHE,-59.,<Fatal hardware error on device> 
-IOER. IE.EOT,-62.,<End of tape detected> 

-IOER. IE.OFL,-65.,<Device off line> 

-IOER. IE.BCC,-66.,<Block check, CRC, or framing error> 
-ILOER. IE.NFW,-69.,<Path lost to partner> ;THIS CODE MUST BE ODD 
-IOER. IE.NDR,-72.,<No dynamic space available> ; SEE ALSO IE.UPN 
-IOER. IE.TMO,-95.,<Timeout on request> 

-IOER. IE.CNR,-96.,<Connection rejected> 


; FILE PRIMITIVE CODES 
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-IOER. IE.NOD,-23.,<Caller's nodes exhausted> 

-IOER. IE.DFU,-24.,<Device full> 

-IOER. IE.JIFU,-25.,<Index file full> 

~IOER. IE.NSF,-26.,<No such file> 

~IOER. IE.LCK,-27.,<Locked from read/write access> 
~IOER. IE.HFU,-28.,<File header full> 

~IOER. IE.WAC,-29.,<Accessed for write> 

~IOER. IE.CKS,-30.,<File header checksum failure> 

-IOER. IE.WAT,-31.,<Attribute control list format error> 
~-IOER. IE.RER,-32.,<File processor device read error> 
-IOER. IE.WER,-33.,<File processor device write error> 
~IOER. IE.ALN,-34.,<File already accessed on LUN> 

~IOER. IE.SNC,-35.,<File ID, file number check> 

~-IOER. IE.SQC,-36.,<File ID, sequence number check> 
-IOER. IE.NLN,-37.,<No file accessed on LUN> 

-IOER. IE.CLO,-38.,<File was not properly closed> 

-IOER. IE.DUP,-57.,<ENTER - duplicate entry in directory> 
~IOER. IE.BVR,-63.,<Bad version number> 

-IOER. IE.BHD,-64.,<Bad file header> 
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FILE CONTROL 
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ERROR CODES 


IE.EXP,-75.,<File expiration date not reached> 
IE.BTF,-76.,<Bad tape format> 
IE.ALC,~-84.,<Allocation failure> 
IE.ULK,-85.,<Unlock error> 
IE.WCK,-86.,<Write check failure> 
IE.DSQ,-90.,<Disk quota exceeded> 


SERVICES CODES 


IE.NBF,-39.,<OPEN - no buffer space available for file> 
IE.RBG,-40.,<Illegal record size> 

IE.NBK,-41.,<File exceeds space allocated, no blocks> 
IE.ILL,-42.,<Illegal operation on file descriptor block> 
IE.BTP,-43.,<Bad record type> 

IE.RAC,-44.,<Illegal record access bits set> 
IE.RAT,-45.,<Illegal record attributes bits set> 
IE.RCN,-46.,<Illegal record number - too large> 
IE.2DV,-48.,<Rename - 2 different devices> 

IE. FEX,-49.,<Rename - new file name already in use> 
IE.BDR,-50.,<Bad directory file> 

IE.RNM,-51.,<Can't rename old file system> 
IE.BDI,-52.,<Bad directory syntax> 

IE.FOP,-53.,<File already open> 

IE.BNM,-54.,<Bad file name> 

IE.BDV,-55.,<Bad device name> 

IE.NFI,-60.,<File ID was not specified> 
IE.1ISQ,-61.,<Illegal sequential operation> 
IE.NNC,-77.,<Not ANSI 'D' format byte count> 


PSI, AND DECDATAWAY CODES 


IE.NNN,-68.,<No such node> 

IE.BLB,-70.,<Bad logical buffer> 
IE.URJ,-73.,<Connection rejected by user> 
IE.NRJ,-74.,<Connection rejected by network> 
IE.NDA,-78.,<No data available> 
IE.IQU,-91.,<Inconsistent qualifier usage> 
ITE.RES,-92.,<Circuit reset during operation> 
IE.TML,-93.,<Too many links to task> 


IE.UKN,-97.,<Unknown name> 


ICS/ICR ERROR CODES 


- IOER. 
- IOER. 
- IOER. 


IE.NLK,-79.,<Task not linked to specified ICS/ICR interrupts> 


IE.NST,-80.,<Specified task not installed> 


IE.FLN,-81.,<Device offline when offline request was issued> 


TTY ERROR CODES 


- IOER. 
- IOER. 


IE.IES,-82.,<Invalid escape sequence> 
IE.PES,-83.,<Partial escape sequence> 


me ™Oe 
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ERROR CODES 


RECONFIGURATION CODES 


~-IOER. IE.ICE,-47.,<Internal consistancy error> 
~IOER. IE.ONL,-67.,<Device online> 


~-IOER. IE.NTR,-87.,<Task not triggered> 
-IOER. IE.REJ,-88.,<Transfer rejected by receiving CPU> 
-IOER. IE.FLG,-89.,<Event flag already specified> 


SUCCESSFUL RETURN CODES--- 


DEFINS IS.PND,+00. ;OPERATION PENDING 
DEFINS IS.SUC,+01. ;OPERATION COMPLETE, SUCCESS 
DEFINS IS.RDD,+02. ;FLOPPY DISK SUCCESSFUL COMPLETION 


;OF A READ PHYSICAL, AND DELETED 
;DATA MARK WAS SEEN IN SECTOR HEADER 


DEFINS IS.TNC,+02. ; (PCL) SUCCESSFUL TRANSFER BUT MESSAGE 
;TRUNCATED (RECEIVE BUFFER TOO SMALL). 
DEFINS IS.BV,+05. ; (A/D READ) AT LEAST ONE BAD VALUE 


;WAS READ (REMAINDER MAY BE GOOD). 
;BAD CHANNEL IS INDICATED BY A 
;NEGATIVE VALUE IN THE BUFFER. 
DEFINS IS.DAO,+02. ;SUCCESSFUL BUT WITH DATA OVERRUN 
7 (NOT TO BE CONFUSED WITH IE.DAO) 


TTY SUCCESS CODES 


Rtas 


DEFINS IS.CR,<15*400+1> ;CARRIAGE RETURN WAS TERMINATOR 
DEFINS IS.ESC,<33*400+1> ;ESCAPE (ALTMODE) WAS TERMINATOR 
DEFINS IS.CC,<3*400+1> ;CONTROL-C WAS TERMINATOR 

DEFINS IS.ESQ,<233*400+1> ;ESCAPE SEQUENCE WAS TERMINATOR 
DEFINS IS.PES,<200*400+1> ;PARTIAL ESCAPE SEQUENCE TERMINATOR 
DEFINS IS.EOT,<4*400+1> ;EOT WAS TERMINATOR (BLOCK MODE INPUT) 
DEFINS IS.TAB,<11*400+1> ;TAB WAS TERMINATOR (FORMS MODE INPUT) 
DEFINS IS.TMO,+2. 7;REQUEST TIMED OUT 


KKKKKK 


THE NEXT AVAILABLE ERROR NUMBER IS: -98. 
NUMBER -71. IS AVAILABLE AND MAY BE REASSIGNED AT 
A LATER DATE 


KKEKK 


IF EQ,$S$MSG 
-MACRO IOERRS A 
. ENDM IOERRS 

. ENDC 


- ENDM ICERRS 
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ERROR CODES 


DEFINE THE DIRECTIVE ERROR CODES RETURNED IN THE DIRECTIVE STATUS WORD 


FILE CONTROL SERVICES (FCS) RETURNS THESE CODES IN THE BYTE F.ERR 
OF THE FILE DESCRIPTOR BLOCK (FDB). TO DISTINGUISH THEM FROM THE 
OVERLAPPING CODES FROM HANDLER AND FILE PRIMITIVES, THE BYTE 
F.ERR+1 IN THE FDB WILL BE NEGATIVE FOR A DIRECTIVE ERROR CODE. 


-MACRO DRERRS SSSGBL 
-MCALL .QIOE.,DEFINS 

IF IDN,<SSSGBL>,<DEFSG> 
~e -GBL=1 

.IFF 

oe -GBL=0 

. ENDC 

-IIF NDF, $SMSG, $$MSG=0 


STANDARD ERROR CODES RETURNED BY DIRECTIVES IN THE DIRECTIVE STATUS WORD 


-QIOE. IE.UPN,-01.,<Insufficient dynamic storage> ; SEE ALSO IE.NDR 
-QIOE. IE.INS,-02.,<Specified task not installed> 

-QIOE. IE.PTS,-03.,<Partition too small for task> 

-QIOE. IE.UNS,-04.,<Insufficient dynamic storage for send> 
-QIOE. IE.ULN,-05.,<Un-assigned LUN> 

-QIOE. IE.HWR,-06.,<Device handler not resident> 

-QIOE. IE.ACT,-07.,<Task not active> 

-QIOE. IE.ITS,-08.,<Directive inconsistent with task state> 
~-QIOE. IE.FIX,-09.,<Task already fixed/unfixed> 

-QIOE. IE.CKP,-10.,<Issuing task not checkpointable> 

-QIOE. IE.TCH,-11.,<Task is checkpointable> 

-QIOE. IE.RBS,-15.,<Receive buffer is too small> 

-QIOE. IE.PRI,-16.,<Privilege violation> 

-QIOE. IE.RSU,-17.,<Resource in use> 

-QIOE. IE.NSW,-18.,<No swap space available> 

-QIOE. IE.ILV,-19.,<Illegal vector specified> 


-QIOE. IE.AST,-80.,<Directive issued/not issued from AST> 
-QIOE. IE.MAP,-81.,<Illegal mapping specified> 

-QIOE. IE.IOP,-83.,<Window has I/O in progress> 

-QIOE. IE.ALG,-84.,<Alignment error> 

-QIOE. IE.WOV,-85.,<Address window allocation overflow> 
-QIOE. IE.NVR,-86.,<Invalid region ID> 

-QITOE. IE.NVW,-87.,<Invalid address window ID> 

»-QIOE. IE.ITP,-88.,<Invalid TI parameter> 

-QIOE. IE.IBS,-89.,<Invalid send buffer size ( .GT. 255.)> 
-QIOE. IE.LNL,-90.,<LUN locked in use> 

-QIOE. IE. IUI,-91.,<Invalid UIC> 

-QIOE. IE.IDU,-92.,<Invalid device or unit> 

-QIOE. IE.ITI,-93.,<Invalid time parameters> 

-QIOE. IE.PNS,-94.,<Partition/region not in system> 
e-QIOE. IE.IPR,-95.,<Invalid priority ( .GT. 250.)> 

-QIOE. IE.ILU,-96.,<Invalid LUN> 

-QIOE. IE.IEF,-97.,<Invalid event flag ( .GT. 64.)> 
-QIOE. IE.ADP,-98.,<Part of DPB out of user's space> 
-QIOE. IE.SDP,-99.,<DIC or DPB size invalid> 


SUCCESS CODES FROM DIRECTIVES - PLACED IN THE DIRECTIVE STATUS WORD 


I-6 
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DEFINS 
DEFINS 


DEFINS 


TR 


eae 


-MACRO 
- ENDM 
- ENDC 
- ENDM 


IS.CLR,0O 

IS.SET,2 

IS.SPD,2 

EQ,$SMSG 

DRERR$ A 
DRERRS 


DRERRS 


ERROR CODES 


; EVENT FLAG WAS CLEAR 

;FROM CLEAR EVENT FLAG DIRECTIVE 
; EVENT FLAG WAS SET 

7;FROM SET EVENT FLAG DIRECTIVE 
;TASK WAS SUSPENDED 


DEFINE THE GENERAL I/O FUNCTION CODES - DEVICE INDEPENDENT 


- MACRO 
-MCALL 
Pa 


-+-GBL=1 


-IFF 


ee ~GBL=0 


- ENDC 


FILIO$ S$SSGBL 
-WORD. ,DEFINS 


IDN,<SSSGBL>,<DEFS$G> 


GENERAL I/O QUALIFIER BYTE DEFINITIONS 


-WORD. 
~WORD. 
-WORD. 
-WORD. 
-WORD. 


IQ. Ky 001,000 
T9.0,002,000 
19.S,004,000 
1Q.UMD, 004,000 


IQ.LCK, 200,000 


EXPRESS QUEUE COMMANDS 


-WORD, 
-WORD. 
- WORD. 
»WORD. 
»WORD. 
-WORD. 


T0.KIL,612,006 
TO.RDN,022,000 
IO.UNL, 042,000 
I0.LTK,050,000 
IO0.RTK,060,000 
I0.SET,030,000 


GENERAL DEVICE HANDLER CODES 


-WORD. 
-WORD. 
-WORD. 
-WORD. 
- WORD. 


IO.WLB,000,001 
TO.RLB,000,002 
I0.LOV,010,002 
I0.ATT,000,003 
I0.DET, 000,004 


DIRECTORY PRIMITIVE CODES 


~WORD. 
»WORD. 
~WORD. 


IO. FNA,000,011 
I0.RNA,000,013 
IO. ENA, 000,014 


;NO ERROR RECOVERY 

;QUEUE REQUEST IN EXPRESS QUEUE 
7;SYNONYM FOR IQ.UMD 

;USER MODE DIAGNOSTIC STATUS REQUIRED 
;MODIFY IMPLIED LOCK FUNCTION 


;KILL CURRENT REQUEST 

71/0 RUNDOWN 

;UNLOAD I/O HANDLER TASK 
;LOAD A TASK IMAGE FILE 
;RECORD A TASK IMAGE FILE 
;SET CHARACTERISTICS FUNCTION 


;WRITE LOGICAL BLOCK 

;READ LOGICAL BLOCK 

;LOAD OVERLAY (DISK DRIVER) 
;ATTACH A DEVICE TO A TASK 
;DETACH A DEVICE FROM A TASK 


;FIND FILE NAME IN DIRECTORY 
;REMOVE FILE NAME FROM DIRECTORY 
; ENTER FILE NAME IN DIRECTORY 


me te 


me we 
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FILE PRIMITIVE 


. WORD. 
. WORD. 
-WORD. 
. WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
. WORD. 
.WORD. 


- MACRO 
- ENDM 
- ENDM 


DEFINE THE I/O FUNCTION CODES 


- MACRO 
»-MCALL 
-IF 

-. GBL=1 
~IFF 

-- GBL=0 
e ENDC 


I/O FUNCTION 


» WORD. 
-WORD. 
-WORD. 
~WORD. 
-WORD. 
- WORD. 
-WORD. 
-WORD. 
-WORD. 
~WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
«WORD. 
-WORD. 
«WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
~WORD. 
»WORD. 
- WORD. 
-WORD. 
-WORD. 


CODES 


IO0.CLN,000,007 
I0.ULK,000,012 
I0.ACR,000,015 
TO.ACW,000,016 
I0.ACE,000,017 
T0.DAC,000,020 
IO.RVB,000,021 
IO0.WVB,000,022 
I0.EXT,000,023 
I0.CRE,000,024 
I0.DEL,000,025 
IO. RAT,000,026 
IO.WAT,000,027 
IO.APV,010,030 
IO0.APC,000,030 


FILIOS A 
FILIOS 
FILIOS 


SPCIOS S$S$SGBL 
~WORD. , DEFINS 


ERROR CODES 


;CLOSE OUT LUN 

;UNLOCK BLOCK 

;ACCESS FOR READ 
;ACCESS FOR WRITE 
;ACCESS FOR EXTEND 
;DE-ACCESS FILE 

;READ VIRITUAL BLOCK 
WRITE VIRITUAL BLOCK 
7;EXTEND FILE 

;CREATE FILE 

;DELETE FILE 

;READ FILE ATTRIBUTES 
;WRITE FILE ATTRIBUTES 
; PRIVILEGED ACP CONTROL 
;ACP CONTROL 


THAT ARE SPECIFIC TO INDIVIDUAL DEVICES 


IDN,<SS$SSGBL>,<DEFS$G> 


IO.WLV, 100,001 
IO.WLS,010,001 
I0.WNS, 020,001 
IO.WAL, 010,001 
I10.WMS, 020,001 
I0.CCO, 040,001 
IO0.WBT,100,001 
IO.WLT,010,001 
IO.WLC, 020,001 
IO.WPB,040,001 
IO0.WDD,140,001 
I0.RLV, 100,002 
IO.RST,001,002 
I0.RAL,010,002 
I0.RNE,020,002 
I10.RNC,040,002 
IO. RTM, 200,002 
I0.RDB, 200,002 
10.SCF,200,002 
I0.RHD,010,002 
I0.RNS,020,002 
I10.CRC,040,002 
I0.RPB,040,002 
I10.RLC,020,002 
I0.ATA, 010,003 
10.GTS,000,005 


CODES FOR SPECIFIC DEVICE DEPENDENT FUNCTIONS 


; (DECTAPE) WRITE LOGICAL REVERSE 

; (COMM.) WRITE PRECEDED BY SYNC TRAIN 

7 (COMM.) WRITE, NO SYNC TRAIN 

; (TTY) WRITE PASSING ALL CHARACTERS 

7 (TTY) WRITE SUPPRESSIBLE MESSAGE 

7 (TTY) WRITE WITH CANCEL CONTROL-O 

7 (TTY) WRITE WITH BREAKTHROUGH 

7 (DISK) WRITE LAST TRACK 

: (DISK) WRITE LOGICAL W/ WRITECHECK 

; (DISK) WRITE PHYSICAL BLOCK 

; (FLOPPY DISK) WRITE PHYSICAL W/ DELETED DATA 
; (MAGTAPE,DECTAPE) READ REVERSE 

; (TTY) READ WITH SPECIAL TERMINATOR 

7 (TTY) READ PASSING ALL CHARACTERS 

7 (TTY) READ WITHOUT ECHO 

7 (TTY) READ - NO LOWER CASE CONVERT 

7; (TTY) READ WITH TIME OUT 

; (CARD READER) READ BINARY MODE 

+ (DISK) SHADOW COPY FUNCTION 

7 (COMM.) READ, STRIP SYNC 

7 (COMM.) READ, DON'T STRIP SYNC 

7 (COMM.) READ, DON'T CLEAR CRC 

7 (DISK) READ PHYSICAL BLOCK 

; (DISK,MAGTAPE) READ LOGICAL W/ READCHECK 
7 (TTY) ATTACH WITH AST'S : 

; (TTY) GET TERMINAL SUPPORT CHARACTERISTICS 


»WORD. 
-WORD. 
- WORD. 
- WORD. 
- WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
«WORD. 
- WORD. 
-WORD. 
-WORD. 
- WORD. 
-WORD. 
-WORD. 
- WORD. 
» WORD. 
- WORD. 
- WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 


-WORD. 
~WORD 


ve Weta @ 


-WORD. 
-WORD. 
-WORD. 
«WORD. 
-WORD. 
-WORD. 
«WORD. 
»WORD. 
~WORD. 
~WORD. 
-WORD. 
»WORD. 
«WORD. 
-WORD. 
»WORD. 
-WORD. 
-WORD. 
-WORD. 
»WORD. 
~WORD. 
-WORD. 
«WORD. 
-WORD. 
-WORD. 
»WORD. 


-WORD. 
»WORD. 
-WORD. 


-WORD. 
-WORD. 


IO0.R1C,000,005 
IO. INL,000,005 
IO0.TRM,010,005 
I0.RWD,000,005 
I0.SPB,020,005 
IO.RPL,020,005 
TO.SPF,040,005 
I0.STC,100,005 
IO.SMD,110,005 
I0.SEC,120,005 
IO. RWU,140,005 
IO0.SMO,160,005 
IO. HNG, 000,006 
IO.RBC, 000,006 
IO.MOD,000,006 
I0.HDX,010,006 
I0.FDX,020,006 
I0.SYN,040,006 
I0.EOF,000,006 
IO. ERS,020,006 


'I0.DSE,040,006 


I0.RTC,000,007 
I0.SA0,000,010 
I0.SS0,000,011 
IO.RPR,000,011 


IO0.MSO,000,012 
TO.RTT,001,012 


ave ee pvva gyi se 


10.SLO,000,013 
I0.MLO,000,014 
I0.LED,000,024 
I0.SDO0,000,025 
10.SDI,000,026 
10.SCS, 000,026 
10.REL, 000,027 
IO.MCS, 000,027 
I0.ADS, 000,030 
10.CCI,000,030 
10. LOD, 000,030 
IO.MDI,000,031 
TO.DCT,000,031 
10. PAD,000,031 
10. XMT, 000,031 
10. XNA,010,031 
10. INI,000,031 
10.HIS, 000,032 
IO. RCI,000,032 
10. RCV, 000, 032 
10. CLK, 000,032 
I0.CSR, 000,032 
I0.MDO, 000,033 
10.CTI,000,033 
I0.CON, 000,033 


I0.STA,000,033 
I0.DTI,000,034 
TO.DIS,000,034 


TO.MDA,000,034 
I0.DPT,010,034 


ERROR CODES 


3; (AFC,AD01,UDC) READ SINGLE CHANNEL 

; (COMM.) INITIALIZATION FUNCTION 

7 (COMM.) TERMINATION FUNCTION 

7 (MAGTAPE,DECTAPE) REWIND 

7 (MAGTAPE) SPACE "N" BLOCKS 

7 (DISK) REPLACE LOGICAL BLOCK (RESECTOR) 


3; (MAGTAPE} 


SPACE "N" EOF MARKS 


;SET CHARACTERISTIC 

; (FLOPPY DISK) SET MEDIA DENSITY 
;SENSE CHARACTERISTIC 

; (MAGTAPE,DECTAPE) REWIND AND UNLOAD 

7 (MAGTAPE) MOUNT & SET CHARACTERISTICS 


pct Ty) 


HANGUP DIAL-UP LINE 


;READ MULTICHANNELS (BUFFER DEFINES CHANNELS) 
; (COMM.) SETMODE FUNCTION FAMILY 

;(COMM.) SET UNIT HALF DUPLEX 

; (COMM.) SET UNIT FULL DUPLEX 

; (COMM.) SPECIFY SYNC CHARACTER 

; (MAGTAPE) WRITE EOF 

; (MAGTAPE) ERASE TAPE 

; (MAGTAPE) DATA SECURITY ERASE 

;READ CHANNEL - TIME BASED 


3; (UDC) 
7; (UDC) 
; (TTY) 
7 (UDC) 


o (/TTVY 


Pyeaey 
; (UDC) 
7 (UDC) 


SINGLE CHANNEL ANALOG OUTPUT 

SINGLE SHOT, SINGLE POINT 

READ WITH PROMPT 

SINGLE SHOT, MULTI-POINT 
R 


RRAN WITH TREDMTNATOD MPA 
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LATCHING, SINGLE POINT 
LATCHING, MULTI-POINT 


TD 
wu 


7 (LPS11) WRITE LED DISPLAY LIGHTS 
;(LPS11) WRITE DIGITAL OUTPUT REGISTER 
; (LPS11) READ DIGITAL INPUT REGISTER 


7 (UDC) 


CONTACT SENSE, SINGLE POINT 


; (LPS11) WRITE RELAY 


i (UDC) 


CONTACT SENSE, MULTI-POINT 


; (LPS11) SYNCHRONOUS A/D SAMPLING 


7 (UDC) 


CONTACT INT — CONNECT 


; (LPA11) LOAD MICROCODE 
7 (LPS11) SYNCHRONOUS DIGITAL INPUT 


7 (UDC) 
7 (PSI) 


CONTACT INT -— DISCONNECT 
DIRECT CONTROL OF X.29 PAD 


7 (COMM.) TRANSMIT SPECIFIED BLOCK WITH ACK 
7 (COMM.) TRANSMIT WITHOUT ACK 


; (LPA11) INITIALIZE 
;(LPS11) SYNCHRONOUS HISTOGRAM SAMPLING 
7 (UDC) CONTACT INT -— READ 


7 (COMM.) RECEIVE DATA IN BUFFER SPECIFIED 
; (LPA11) START CLOCK 

7 (BUS SWITCH) READ CSR REGISTER 

+ (LPS11) SYNCHRONOUS DIGITAL OUTPUT 


; (UDC) 


TIMER -— CONNECT 


; (COMM.) CONNECT FUNCTION 


3 (VT11) 


- CONNECT TASK TO DISPLAY PROCESSOR 


; (BUS SWITCH) CONNECT TO SPECIFIED BUS 
; (LPA11) START DATA TRANSFER 


; (UDC) 


TIMER -— DISCONNECT 


; (COMM.) DISCONNECT FUNCTION 
;(VT11) - DISCONNECT TASK FROM DISPLAY PROCESSOR 
; (BUS SWITCH) SWITCHED BUS DISCONNECT 


: (LPS11) 


SYNCHRONOUS D/A OUTPUT 


; (BUS SWITCH) DISCONNECT TO SPECIF PORT NO. 


T-9 
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-WORD. 
~WORD. 
-WORD. 


-WORD. 
-WORD. 
- WORD. 


IO.RTI,000,035 
IO0.CTL,000,035 
I0.STP,000,035 


TO. SWI,000,035 
I0.CNT,000,036 
IO. ITI,000,036 


COMMUNICATIONS FUNCTIONS 


.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 
.WORD. 


I0.CPR,010,033 
I0.CAS,020,033 
I0.CRJ,040,033 
I0.CBO,110,033 
I0.CTR, 210,033 
TO.GNI,010,035 
I0.GLI,020,035 
I0.GLC,030,035 
I0.GRI,040,035 
I0.GRC,050,035 
T0.GRN,060,035 
IT0.CSM,070,035 
I0.CIN,100,035 
I0.SPW,110,035 
I0.CPW,120,035 
IO.NLB,130,035 
I0.DLB,140,035 


ICS/ICR I/O FUNCTIONS 


-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
~WORD. 
»WORD. 
-WORD. 
»WORD. 
-WORD. 


10.CTY,000,007 
I0.DTY,000,015 
IO0.LDI,000,016 
I0.UDI,010,023 
IO0.LTI,000,017 
I0.UTI,020,023 
I0.LTY,000,020 
I0.UTY,030,023 
I0. LKE,000,024 
IO.UER, 040,023 
IO.NLK,000,023 
IO0.ONL,000,037 
I0.FLN,000,025 
I0.RAD,000,021 


IP11 I/O FUNCTIONS 


-WORD. 
~WORD. 
~WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
-WORD. 
~WORD. 


IO0.MAO,010,007 
I0.LEI,010,017 
TO.RDD,010,020 
IO. RMT,020,020 
IO.LSI,000,022 
IO.UEI,050,023 
TO.USI,060,023 
I0.CSI,000,026 
IO.DSI,000,027 


ERROR CODES 


3 (UDC) TIMER - READ 

; (COMM.) NETWORK CONTROL FUNCTION 
7 (LPS11,LPA11) STOP IN PROGRESS FUNCTION 
;(VT11) - STOP DISPLAY PROCESSOR 

7 (BUS SWITCH) SWITCH BUSSES 

;(VT11) - CONTINUE DISPLAY PROCESSOR 
7 (UDC) TIMER - INITIALIZE 


CONNECT NO TIMEOUTS 

;CONNECT WITH AST 

CONNECT REJECT 

;BOOT CONNECT 

; TRANSPARENT CONNECT 

;GET NODE INFORMATION 

;GET LINK INFORMATION 

;GET LINK INFO CLEAR COUNTERS 
;GET REMOTE NODE INFORMATION 
;GET REMOTE NODE ERROR COUNTS 
;GET REMOTE NODE NAME 

;CHANGE SOLO MODE 

;CHANGE CONNECTION INHIBIT 
;SPECIFY NETWORK PASSWORD 
;CHECK NETWORK PASSWORD. 

;NSP LOOPBACK 

7DDCMP LOOPBACK 


7;CONNECT TO TERMINAL INTERRUPTS 
7;DISCONNECT FROM TERMINAL INTERRUPTS 
;LINK TO DIGITAL INTERRUPTS 

7;UNLINK FROM DIGITAL INTERRUPTS 

;LINK TO COUNTER MODULE INTERRUPTS 
;UNLINK FROM COUNTER MODULE INTERRUPTS 
;LINK TO REMOTE TERMINAL INTERRUPTS 
;UNLINK FROM REMOTE TERMINAL INTERRUPTS 
;LINK TO ERROR INTERRUPTS 

:UNLINK FROM ERROR INTERRUPTS 

;UNLINK FROM ALL INTERRUPTS 

7;UNIT ONLINE 

7UNIT OFFLINE 

;READ ACTIVATING DATA 


;MULTIPLE ANALOG OUTPUTS 

;LINK EVENT FLAGS TO INTERRUPT 
;READ DIGITAL DATA 

;READ MAPPING TABLE 

;LINK TO DSI INTERRUPTS 

;UNLINK EVENT FLAGS 

;UNLINK FROM DSI INTERRUPTS 
;CONNECT TO DSI INTERRUPTS 
;DISCONNECT FROM DSI INTERRUPTS 


me te 
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PCL11 


DEFINE THE I/O CODES FOR USER-MODE DIAGNOSITCS. 


I/O FUNCTIONS 


>WORD. 
-WORD. 
»WORD. 
~WORD. 
-WORD. 


- MACRO 
- ENDM 
« ENDM 


TO.ATX,000,001 
IO.ATF,000,002 
TO.CRX,000,031 
I0.DRX,000,032 
IO.RTF,000,033 


SPCIOS A 
SPCIOS$ 
SPCIOS$ 


ERROR CODES 


;ATTEMPT TRANSMISSION 

; ACCEPT TRANSFER 

;CONNECT FOR RECEPTION 
;DISCONNECT FROM RECEPTION 
;REJECT TRANSFER 


ALL DIAGNOSTIC 


FUNCTION ARE IMPLEMENTED AS A SUBFUNCTION OF I/O CODE 10 (OCTAL). 


. GBL=1 
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DEFINE USER-MODE DIAGNOSTIC FUNCTIONS. 


MACRO 


-MACRO UMDIOS S$SSGBL 


~MCALL 


»WORD. ,DEFINS 


-IF IDN <$$S$GBL>,<DEFS$G> 


- WORD. 


-WORD. 
~WORD. 
-WORD. 
«WORD. 
~WORD. 
-WORD. 
-WORD. 
»WORD. 
»WORD. 
-WORD. 
-WORD. 
-WORD. 
»WORD. 
»WORD. 
-WORD. 
»WORD. 
»WORD. 


TQ.UMD, 004,000 


TO.HMS,000,010 
TO.BLS,010,010 
I0.OFF,020,010 
I0.RDH,030,010 
IO.WDH, 040,010 
IO0.WCK,050,010 
IO. RNF,060,010 
IO. RNR,070,010 
TO. LPC,100,010 
IO0.RTD,120,010 


‘IO.WTD, 130,010 


IO. TDD, 140,010 
I0.DGN, 150,010 
I0.WPD, 160,010 
IO.RPD,170,010 
I0.CER, 200,010 
I0.CEW, 210,010 


REDEFINITION TO NULL 


-MACRO UMDIOS A 


.- ENDM 


.» ENDM 


UMDIO$ 


;USER MODE DIAGNOSTIC REQUEST 


; (DISK) 
; (DISK) 
; (DISK) 
; (DISK) 
; (DISK) 
; (DISK) 


HOME SEEK OR RECALIBRATE 
BLOCK SEEK 

OFFSET POSITION 

READ DISK HEADER 

WRITE DISK HEADER 
WRITECHECK (NON-TRANSFER) 


; (DECTAPE) READ BLOCK NUMBER FORWARD 
; (DECTAPE) READ BLOCK NUMBER REVERSE 
; (MAGTAPE) READ LONGITUDINAL PARITY CHAR 


; (DISK) 
; (DISK) 
; (DISK) 


READ TRACK DESCRIPTOR 
WRITE TRACK DESCRIPTOR 
WRITE TRACK DESCRIPTOR DISPLACED 


;DIAGNOSE MICRO PROCESSOR FIRMWARE 


; (DISK) 
; (DISK) 
; (DISK) 
; (DISK) 


WRITE PHYSICAL BLOCK 
READ PHYSICAL BLOCK 
READ CE BLOCK 

WRITE CE BLOCK 


=e Te TO SMO 


me we NO me ™e Me Ne Me 


™e Me Me 


ERROR CODES 


HANDLER ERROR CODES RETURNED IN I/O STATUS BLOCK ARE DEFINED THROUGH THIS 
MACRO WHICH THEN CONDITIONALLY INVOKES THE MESSAGE GENERATING MACRO 
FOR THE QIOSYM.MSG FILE 


«MACRO 
DEFINS 
IF 
-MCALL 
- IOMG. 
- ENDC 
- ENDM 


.IOER. SYM,LO,MSG 
SYM,LO 

GT, $$MSG 

.IOMG. 

SYM, LO,<MSG> 


-IOER. 


I/O ERROR CODES ARE DEFINED THOUGH THIS MACRO WHICH THEN INVOKES THE 
GENERATING MACRO, ERROR CODES -129 THROUGH 
ARE USED IN THE QIOSYM.MSG FILE > 


ERROR MESSAGE 


-MACRO 
DEFINS 
IF 
-MCALL 
- IOMG. 
- ENDC 
. ENDM 


CONDITIONALLY 


-MACRO 
«WORD 

- ENABL 
»ASCIZ 
- DSABL 


mermar 


e HVGIN 
- TIF 
- ENDM 


-QIOE. SYM,LO,MSG 
SYM,LO 

GT, $SMSG 

- IOMG. 
SYM,<LO-128.>,<MSG> 


~QIOE. 


GENERATE DATA FOR WRITING A MESSAGE FILE 


~IOMG. SYM,LO,MSG 


LT, “O<SSSMAX+<LO>> , SSSMAX=-“O<LO> 


- IOMG. 


DEFINE THE SYMBOL SYM WHERE LO IS IS THE LOW ORDER BYTE, 


«MACRO 
DEFINS 
- ENDM 


- DSABL 


-WORD. SYM,LO,HI 
SYM,<HI*400+L0> 
-WORD. 


LC 


-256 


HI IS THE HIGH BYTE 


Definitions 


S.BFHD 
S.FATT 
S.FDB 
S.FNAM 
S.FNB 


S.FNBW 


S.FSR2 


S.FTYP 


S.NFEN 


for these 


- Size 
- Size 
- Size 
- Size 
- Size 
- Size 


= Size 


of 


of 


of 


of 


of 


of 


of 


we 


RAD-50) 


- Size 
= Size 


- Size 
type, 


of 


of 


of 


APPENDIX J 


FIELD SIZE SYMBOLS 


symbols are contained in the System Library. 


FSR block buffer header in bytes 


FDB file attribute area in bytes 


FDB in bytes (including name block) 


file name in bytes (stored in RAD-50) 


filename block in bytes 


filename block in words 


file name and file type in words (stored in 
FSR2 (basic impure area) 

File type in bytes (in RAD-50) 

a complete file name in bytes -- file ID, name, 


and version 


APPENDIX K 


RSX-11M/M-PLUS FCS LIBRARY SYSGEN OPTIONS 


K.1 FCS LIBRARY OPTIONS 


The system manager has the option of selecting one of several FCS 
libraries as the default FCS library. You can replace the default 
library in SYSLIB with one of the other libraries shown in Table K-1l 
by using the /RP switch to the LBR utility. Refer to the 
RSX-11M/M-PLUS Utilities Manual for more information. The following 
list contains the FCS libraries that are avaitabite with each RSX-11M 


r¥a Wr 


or RSX-11M-PLUS system, and a brief description of each. 


Table K-1l 
FCS Library Descriptions 


Per | pe | 


CS Library Support Description 


[1,1JFCS.OBJ Standard FCS routines. Distributed and 
included in SYSLIB.OLB as the default FCS 
library routines for RSX-i1M. 


[1,1] FCSMTA. OBJ Includes standard FCS routines, plus ANSI 
magtape support and "big buffering" (see 
Section 2.2.1.6 for block buffer size 
override specification). Distributed and 
included as the default FCS library 
routines for RSX-11M-PLUS. 


{1,1]FCSMBF.OBJ Provides multiple buffering support, big 
buffering support, and ANSI magtape support 
in addition to the standard FCS routines. 


K.2 .FCTYP 


The FCS routine, .FCTYP, returns a description of the FCS conditional 
assembly parameters that were set when FCS was built. 


The format of the call is: 
CALL ~FCTYP 


There are no input parameters. 


RSX-11M/M-PLUS FCS LIBRARY SYSGEN OPTIONS 


The information is returned in Rl. The bits set in the mask word 
returned in Rl correspond to the conditional assembly parameters as 


shown in Table K-2. 


Table K-2 
-FCTYP Values 


Conditional 
Assembly Symbol Rl Bit Mask Symbol Meaning 


FT. ANI ANSI magnetic tape support 
FT.BBF Big buffer support 


FT.MBF Multibuffer support 


INDEX 


ACTFIL command, 2-41 
Action routines, 7-6 
ANSI filename block format, 
B-5 
ANSI magnetic tape, 5-4, G-l, 
G-10 
creating volume, G-ll 
end-of-tape, G-9 
end-of-volume label, G-7 
file header block, G-9 
file header format, 


G-5 to G-6 
file header labels, 
| eee aa 


en =A 
file name conversion, G-6 
file structure, G-8 
file trailer labels, G-7 
FNB offset defintions, B-4 
opening file by file ID, 
3-14 
override biock size, 2-18 
rewinding file, 4-18 
set default block size, G-10 
user file labels, G-8 
user volume labels, G-3 
volume iabel format, 
G-1l to G-4 
ANSI magtape file name, 6-13 
conversion to RADIX-50, 4-15 
dataset descriptor, 2-29 
-FIND operation on, 4-15 
-PARSE, 4-8 
restriction on NMBLKS, 2-33 
~ASCPP, 4-7 
ASG directive, 
task builder, 6-13 
~ASLUN, 4-12 
Assign Logical Unit Number, 
4-12 
AST, 
block I/O completion, 2-44 
AST service routine, 
restrictions, 2-45 
specifying address, 2-44 
Asynchronous transfer, 3-37 
Automatic file truncation, 
4-22 
disabling, 4-22 
enabling, 4-22 


Bad Block File Header, E-2 
Big buffering, 1-7, 3-21, 3-27 
Big buffers, 

choosing size for, 1-8 


Index-1 


Big buffers (Cont.) 

using, 1-8 
Block buffer size, 3-21, 3-27 
Block I/0, 3-30, 3-35 
Block I/O completion, 3-35 
Block locking, 

enabling, 2-15 
Block size, 

Parameter to FDBKSA, 2-11 
Boostrap block, E-1 
Buffer address, 

parameter to FDBKSA, 2-11 
Built-in variables, 7-5 


Calculating length of the FSR, 
2-40 
CALL macro, 4-1 
Carriage control, 
specifying, for unlabeled 
tape, G-ll 
CCMLS, 6-9, 6-12 
Checkpoint File Header, E-2 
Choosing buffer size, 1-8 
Clearing terminal end of file, 
4-25 
CLOSES, 
automatic file truncation, 
4-22 
effect of on F.CNTG, 2-7 
CLOSES macro call, 
format, 3-18 
Closing a file, 3-17 
Closing magtape volume, 4-25 
Command line, 
ignoring blanks and tabs, 
7-8 
Command line parsing, 
errors, 6-21 
Command line processing, 6-1 
data flow during, 6-2 
Command Semantic Parser, 
6-19 to 6-20 
Command String Syntax 
Analyzer, 6-18 to 6-19 
Continuation lines, 6-5 
Control bits for .EXTND, 
4-23 to 4-24 
Control information, 
parameter to FDOPSA, 2-15 
Creating a new file, 3-4, 3-7 
CSI, 6-1, 6-13 to 6-14, 6-18, 
6-20 to 6-27, 6-29 
numeric conversion, 6-28 
CSIS, 6-14 


INDEX 


CSI Control block, 
6-14 to 6-17 
CSI Run-time macro calls, 6-18 
CSIS1, 6-18 to 6-19 
CSIS2, 6-18 to 6-21 
CTRL, 4-25, 5-6 


Dataset descriptor, 1-10, 
2-27 to 2-28, 3-15 
definition of, 1-11 
parameter to FDOPSA, 2-13 
Dataset-descriptor pointer, 
definition of, 1-11 
Debug routine, 7-6 to 7-7, 
7-11 
Declaring FCS macros, 2-3 
Default buffer count, 
changing, 2-20 
Default buffer size, 1-8, 2-41 
Default directory, 
inserting, 4-17 
Default extend size, 2-19 
establishing, 2-8 
volume, 2-8 
Default file name, 
parameter to NMBLKS, 2-31 
Default file name block, 1-10, 
2-27, 2-30, 3-4, 3-15 
definition of, 1-11 
initializing directly, 2-32 
parameter to FDOPSA, 2-14 
Default file name block label, 
parameter to NMBLKS, 2-31 
Default file protection, 
4-4 to 4-5 
reading, 4-5 
word format, 4-5 
writing, 4-5 
Default file type, 
parameter to NMBLKS, 2-31 
Default file version number, 
parameter to NMBLKS, 2-31 
Default name of device, 
parameter to NMBLKS, 2-31 
Default UIC, 4-4 
reading, 4-4 
writing, 4-4 
DELETS, 3-38 
format, 3-38 
parameters, 3-38 
Delete Directory Entry, 4-16 
Device and unit, 
parsing, 4-9, 4-12 
Directive status codes, 
I-l to I-12 
Directory entry, 
deleting, 4-16 


Index-2 


Directory entry (Cont.) 
deleting wildcard, 4-16 
inserting, 4-15 
locating, 4-13 

Directory files, 5-2 

Directory Identification, 
parsing, 4-10 

Directory information, 
inserting, 4-16 
parsing, 4-12 

Directory string, 
reading, 4-2 
writing, 4-2 to 4-3 

Directory Structure, 
multiuser volume, 5-3 
Single-user volume, 5-2 


EBCDIC, G-17 
Enabling block locking, 2-15 
-ENTER, 4-15 
Error handling, 

.PRINT, 8-2 

PRINTS, 8-2 
Event flag, 

parameter to FDBFSA, 2-17 

parameter to FDBKSA, 2-12 

using for I/O operations, 

2-42 

Executive directives, 

summary, C-1l to C-3 
Existing file, 

opening by file ID, 3-14 
Extend size, 

default, 2-8 

volume default, 2-8 
Extending a file, 4-21 
Extension headers, F-6 
~EXTND, 4-21 

control bits for, 

4-23 to 4-24 

effect of on F.CNTG, 2-7 
EXTSCT Task-build command, 

to extend FSR size, 2-40 


F11IACP, F-6 
F.ALOC, 
See Extend size 
F.CNTG, 2-6 to 2-7 
FCS, 4-1 
characteristics of, 1-12 
conditional assembly 
parameters, K-l to K-2 
FCS impure area, 
allocating, 2-37 
FCS library descriptions, K-1 


FCS library options, 

FCS macros, 
declaring, 

FCS routines, 
error return, 

LISE-OL 4° A=2 
-FCTYP values, 
FDB, 1-10 

block access section, 2-10 

block buffer section, A-2 

file attribute section, A-2 

file open section, A-2 

format, A-2 

GETS, 3-20 

offset definitions, 

A-3 to A-4, A-6 to A-8 
offset defintions, A-5 
PUTS, 3-26 
READS, 3-34 
record access section, 
record or block access 

section, A-2 
WRITES, 3-35 

FDB information, 2-2 

macro calls, 2-2 
FDB macros, 

initializing, 2-3 
FDBDFS, 2-5 
FDBFSA, 

using with big buffers, 
FDBFSA macro call, 

format, 2-17 
FDBFSR, 

uSing with big buffers, 
FDBKSA, 2-10 

format, 2-11 

parameters, 
FDBKSR, 

compatability with FDBKSA, 

2-11 

FD.BLK, 

See Record 
FD.CR, 

See Record 
F.DFNB, 2-14 
FD.FTN, 

See Record 
FD.PRN, 

See Record 
FDRCSA, 

format, 2-8 
F.DSPT, 2-13 
F.FACC, 2-14 
Field size symbols, J-1l 
File, 

closing, 3-17 

creating, 3-4, 

deleting, 3-38, 


2-3 


4-2 


K=2 


2-8 


2=11 


attributes 


attributes 


attributes 


attributes 


3-7 
4-23 


Index-3 


INDEX 


le (Cont.) 
deieting by Filename block, 
4-24 
deleting wildcard, 4-15 
extending, 4-21 
opening an existing, 3-4, 
3-8 
opening by filename block, 
3-14 
positioning, 4-18 to 4-19 
renaming, 4-20 
rewinding, 4-18 
File access, 3-16 
Parameter to FDOPSA, 2-14 
file access privileges, 3-3 
File Control Services (FCS), 
4-1 
File Descriptor Block, 
A-1 
definition of, 1-10 
format, A-l to A-2 
offset definitions, 
A-3 to A-8 
offsets, A-l 
File extension, 
See File type 


File header area, 
characteristics, 
file number, F-3 
file owner, F-4 
file protection, F-4 
file sequence number, F-3 
identification area, F-3 
Map area offset, F-3 
structure level, F-4 
user file attributes, 


File header block, 5-3 
file header area, F-3 
format, F-2 
identification area, F-4 
map area, F-5 
predefined, E-2 

file header block, 
format, F-1l 

File ID, 
opening file by, 2-33, 

File identifier, 
processing by Files-lii, G-6 

File locking, 2-15 

File owner, 
nonprivileged user, 4-5 
privileged user, 4-6 

File owner word, 4-5 
format, 4-6 
reading, 4-6 
writing, 4-6 

File processing, 
magnetic tape, 


1-10, 


F-4 


F=4 


5-13 


5-4 


File specification, 2-27 
definition of, 1-1l 
File specifier, 
See File specification 
File Storage Region, 
definition of, 1-11 
initializing, 2-36 
File structure, 5-1 
ANSI magtape, G-8 
user, 5-l 
File truncation, 
automatic, 4-22 
PUTS, 2-9 
File type, 
parsing, 4-11 to 4-12 
File version, 
0, 4-16 
default, 4-16 
parsing, 4-11 to 4-12 
special versions, 4-13 
wildcard, 4-16 
Filename, 
parsing, 4-8, 
Filename block, 
ANSI format, B-5 
default directory, 
definition of, 1-11 
deleting by, 4-24 
directory information, 4-16 
R-1, B-3 
initializing, 2-35 
offset definitions, 
offsets, B-1l 
offsets for ANSI magtape, 
B-4 
Status word, 4-ll, 
B-3 to B-4 
File-processing macro calls, 
3-1 
error handling, 
Files-ll, 5-l, 
G-6 
file identifier processing, 
G-5 
naming convention, G-3 
-FIND, 4-13 to 4-14 
effects of NB.ANS, 4-15 
wildcard operations, 4-13 
FINITS macro, 2-39 
format, 2-39 
Fixed length record, 
magtape, 1-4 
F.MBCT, 2-18 
FORTRAN programs, 
increasing FSR size, 2-41 
F.RACC, 
See FDB 
F.RATT, 2-6 


4-11 to 4-12 


4-17 


format, 


B-2 


3-2 


E-1l, F-5, G-3, 


1-4 


Index-4 


INDEX 


FSR, 
calculating length, 2-40 
changing the size of, 1-3 
initializing, 2-36, 2-39 
number of block buffer 

headers, 1-2 
number of block buffers, 

FSR size, 
for command file, 

SSFSR1, 1-2 
FSR program section, 2-40 

SSFSR2, 1-2, 4-2, 4-4 to 4-5 

FSRSZS$, 2-37 

FSRSZS macro, 
format, 2-37 
parameters, 


1-2 


6-13 


2-36 


2-37 


GCML, 6-1 to 6-13 
run-time calls, 6-9 
usage considerations, 

GCMLS,; 6-9 to 6-11 

GCML control block, 6-3 
offsets, 6-6 to 6-9 

GCML control block offsets, 
referencing, 6-9 


6=13 


GCMLBS, 6-4 to 6-5 
GCMLDS, 6-6 to 6-9 
Generating a parser program, 
7-14 
GETS, 
FDB, 3-20 
locate mode, 3-18 
move mode, 3-18, 3-21 


GETS macro call, 
format, 3-19 
parameters, 

GETSR, 3-22 

GETSR macro call, 
format, 3-22 
parameters, 

GETSS, 3-24 

-GTDID, 3-15, 

-GTDIR, 3-15, 


3-19 


3-23 


4-17 
4-16 


Home block, E-2 
format, E-3 


IBM magnetic tape, 
reading, G-18 to G-19 
Increasing FSR size, 
FORTRAN programs, 
MACRO-11 programs, 


2-41 
2-40 


Index file, 5-2, 
bit map, E-2 
format, E-1l 
header, E-2 

Indirect command files, 

6-11 to 6-12 
maximum nesting depth, 
6-3 to 6-4 

Insert Directory Entry, 4-15 

I/O Error Codes, I-1 to I-12 

I/O Function codes, 

I-1 to I-12 

I/O operations, 
event flag use, 2-42 

I/O related directives, 
summary, C-2 to C-3 

I/O status block, 2-43 
parameter to FDBKSA, 2-12 
READS operations, 2-43 
second word, 2-43 
status codes, 2-44 

I/O-related directives, 
summary, C-l 


IOSTAT, 2-44 
ISTATS, 7-2, 


E-1 


6-3, 


E fae 


bwe 


Keyword, 
abbreviation, 
recognition, 

Keyword table, 


THLZ 
7-9 
Pal 


Locate Directory Entry, 4-13 
Locate mode, 1-6 
GETS, 3-18 
GETS operations, 3-21 
PUTS, 3-27 
Logical unit number, 
assigning, 4-12 


parameter to FDOPSA, 2-13 


Macro calls, 2-2 
assembly time, 2 
file-processing, 
run-time, 2-2 

MACRO-11 programs, 
increasing FSR size, 

MAG, G-10 

MAG command, 
format, G-10 

MAG SET, 

/BS, G-10 
/CC, G-ll 


-2 
2-2 


2-40 


INDEX 


Index-5 


MAG SET (Cont.) 
/EOF, G-1l 
/POS, G-16 
/REWIND, G-12, G-16 
/RS, G-12 
MAG SET command, G-10, G-16 
error messages, G-13 to G-15 
example, G-12 
MAG SET /EOT, G-il 
MAG SET /EOV, G-1l 
MAG SET /INITIALIZE, 
MAG SET /POS, G-1ll 
Magnetic tape, 5-4 
closing a file, 5-8 
closing volume, 4-25 
examples, 5-9 to 5-10 
multiple-file operations, 
5-6 
overriding FCS defaults, 
5-6 to 5-7 
position to EOT, 
positioning, 5-5, 
processing examples, 
reading a file, 5-8 
reading IBM, G-18 to G-19 
rewinding, 4-25 
rewinding file on, 4-25 
single-file operations, 
translation, G-16 
Magnetic Tape Control Task, 
G-10 
Magnetic 


G-11l 


4-25 
G-1l 
5=7 


5-5 


tape poSition, 2-15 
Magnetic tape volume, 
access, 5-4 
creating multiple file, 
rewinding, 5-5 
Magnetic tape volume set, 
rewinding, 5-5 
-MARK, 4-18 to 4-19 
Master File Directory, 5-2 
Master File Directory Header, 
E-2 
Move mode, 1-6 
GETS, 3-18 
GETS operations, 3-21 
PUTS, 3-26 
e-MRKDL, 4-23 
Multiple buffer count, 
parameter to FDBFSA, 2-18 
parameter to FSRSZ$, 2-38 
Multiple buffering, 1-6, 3-10 
effect on FSRSZS$, 2-37 
read-ahead, 1-7, 2-18 
type of, 2-18 
versus Single buffering, 1-7 
write-behind, 2-19 
Multiple-buffered record I/0, 
3-10 


5-6 


NB.ANS, 
bit in N.STAT, 
NMBLKS, 
general method of 
specifying, 2-32 
macro call, 2-30 
parameters, 2-31 
NMBLKS macro, 3-15 


4-15 


wildcard .FIND operations, 
4-13 


OFNBSX macro call, 
format, 3-14 

OPENS macro call, 
format, 3-17 

Opening a file, 3-2 

Opening a new file, 3-8 


Opening an existing file, 3- 


3-8 
by file ID, 3-14 
Opening by file ID, 
2-33 to 2-34, 3-13 
Opening filename block, 
OPENSx, 
restrictions, 3-3 
suffixes for, 3-2 
OPENSx macro call, 
file access privileges, 
format, 3-5 
Override block size, 
ANSI magtape, 2-18 
parameter to FDBFSA, 2-17 
Overriding default buffer 
size, 1-8 
Overriding FCS defaults for 
magtape, 5-7 


3-14 


3- 


-PARSE, 4-8 
Parser program, 
generating, 7-14 
-POINT, 2-9, 4-18 
restrictions, 4-18 
-POSIT, 4-20 
Positioning to end of tape, 
4-25 
~POSRC, 
-PPASC, 
-PRINT, 
error 
PRINTS, 
error 


3-24, 
4-7 


3429, 2-19 


handling, 8-2 


handling, 8-2 
error returns, 8-l 
macro, 8-1 

Print Spooling, 8-1 


INDEX 


4, 


3 


Index-6 


-PRINT subroutine, 8-2 
Program section, 
generated by TPARS, 
Prompt, 
user-specified, 
PSECT, 7-10 
PUTS, 3-24 
FDB, 3-26 
locate mode, 3-24, 3-27 
move mode, 3-24, 3-26 
random mode, 3-24 
PUTS macro call, 
format, 3-25 
parameters, 
PUTSR, 3-28 
PUTSR macro call, 
format, 3-29 
parameters, 
PUTSS, 3-30 
PUTSS format, 
See PUTS 


7=10 


6-4, 6-10 


3-2 


3-29 


QIOS directive, 


QIO function, 
executing, 4-20 


2-41 to 2-42 


3-22 
6-12 


Random mode, 
RCMLS, 6-9, 
-RDFDR, 4-2 
»RDFFP, 4-5 
~RDFUI, 4-4 
READS, 3-30 
FDB, 3-34 
Read logical record, 
locate mode, 3-18 
move mode, 3-18 
random mode, 3-24 
READS macro call, 
format, 3-31 
parameters, 3-31 to 3-33 
Read virtual block, 3-30 
Read-ahead multiple buffering, 
1-7, 2-18 
Record access byte, 
initializing, 2-9 
Record access section of FDB, 
2-8 
Record attribute byte, 
Record attributes, 2-6 
Record I/0, 
contrast to block I/0, 
data flow during, 1-3 
multiple buffered, 3-10 
multiple buffering, 1-6 
random access mode, 1-5 


2-6 


Ti 
seer’) 


INDEX 


Record I/O (Cont.) System directives, 
sequential access mode, 1-5 summary, C-l to C-3 

Record I/O operations, 3-24 

Record size, 2-6 

Record type, 


R.FIX, 2-5 Table Driven Parser, 7-1 
R.SEQ, 2-6 Tape mark, G-16 
R.VAR, 2-6 Task builder, 2-41 
~REMOV, 4-16 ASG directive, 6-13 
~RENAM, 4-20 Temporary file, 
Request for next tape, creating, 3-11 
terminating, G-1l deleting, 4-23 
Retrieval pointer format, F-5 marking, for deletion, 3-12 
Retrieval pointers, opening, 3-11 
allocating, 2-15 Terminal, 
Rewinding, rewinding file open on, 4-18 
file on ANSI magtape, 4-18 TPARS, 7-1 to 7-11, 7-14 
file open on terminal, 4-18 calling conventions, 7-12 
Rewinding magtape, 4-25 options word, 7-12 
Rewinding magtape volume, 4-25 programming examples, 


7-15 to 7-18 
register usage, 7-12 
subexpressions, 7-19 


Sample programs, D-1l TRANS macro, 7-4 
Shared file access, Transition, 
OPENSR, 1-9 defining, 7-3 
OPNSSA, 1-9 rejecting, 7-6, 7-18 
OPNSSR, 1-9 Translation, 
OPNSSU, 1-9 EBCDIC, G-17 to G-18 
OPNSSW, 1-9 installation-dependent 
Permitted second access, 1-9 routines, G-17 
Single buffering, magnetic tape, G-17 
versus multiple buffering, Translation table, 
1-7 EBCDIC, G-17 to G-18 
Special characters, e-TRNCL, 4-22 
entering, 7-9 Truncation of file, 
Spooling, 8-1 PUTS, 2-9 


State table, 7-2, 7-8 
initializing, 7-2 
Statistics block, 3-1l 


format, H-l UIC, 
Storage Map File header, E-2 default, 4-4 
Subexpression, UIC conversion, 
using, 7-19 ASCII to binary, 4-7 
Subexpressions, binary to ASCII, 4-7 
TPARS, 7-7 Unit number, 
Switch Definition, Parameter to NMBLKS, 2-31 
6-21 to 6-26 Unlabeled tape, G-15 
Switch Descriptor Table, example, G-12 
6-22 to 6-26 file attributes, G-16 
end, 6-29 positioning, G-ll, G-16 
format of entry, 6-26 specifying block size, G-10 
Switch Value Descriptor Table, specifying carriage control, 
6-27 G-11 
end, 6-29 specifying record size, G-12 
entry format, 6-28 User File Directory, 5-2 
Syntax element, User record buffer, 
defining, 7-3 parameter for FDRCSA, 2-9 
types, 7-4 to 7-5, 7-8 size, 2-10 
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User record buffer size, WAITS macro call (Cont.) 
parameter for FDRCSA, 2-10 parameters, 3-36 to 3-37 
User volume lables, -WDFDR, 4-3 
ANSI magtape, G-3 -WDFFP, 4-5 
User-specified prompt, 6-4, -WDFUI, 4-4 
6-10 Wildcard operations, 4-14 
Using big buffers, 1-8 effects of N.STAT, 4-13 


-FIND, 4-13 
WRITES, 3-34 


FDB, 3-35 
Variable-length record, Write logical record, 
mMagtape, 1-4 random mode, 3-28 
nonsequenced, 1-4 sequential mode, 3-30 
sequenced, 1-4 WRITES macro call, 
VFY, 3-12 format, 3-34 to 3-35 
Virtual block, parameters, 3-35 
definition of, 1-3 Write virtual block, 3-34 
Virtual block on magtape, 1-4 Write-behind multiple 


buffering, 2-19 


WAITS, 3-35 to 3-36 
WAITS macro call, 
format, 3-36 -XQIO, 4-20 
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